mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2026-08-24 02:34:19 -05:00
chore: add agent context
Entire-Checkpoint: 109fcbd963a8
This commit is contained in:
committed by
Jan De Dobbeleer
parent
80764bdb55
commit
9f8196e162
@@ -0,0 +1,323 @@
|
|||||||
|
---
|
||||||
|
name: ast-grep
|
||||||
|
description: Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.
|
||||||
|
---
|
||||||
|
|
||||||
|
# ast-grep Code Search
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
Use this skill when users:
|
||||||
|
- Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
|
||||||
|
- Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
|
||||||
|
- Request searches that require understanding code structure rather than just text
|
||||||
|
- Ask to search for code with particular AST characteristics
|
||||||
|
- Need to perform complex code queries that traditional text search cannot handle
|
||||||
|
|
||||||
|
## General Workflow
|
||||||
|
|
||||||
|
Follow this process to help users write effective ast-grep rules:
|
||||||
|
|
||||||
|
### Step 1: Understand the Query
|
||||||
|
|
||||||
|
Clearly understand what the user wants to find. Ask clarifying questions if needed:
|
||||||
|
- What specific code pattern or structure are they looking for?
|
||||||
|
- Which programming language?
|
||||||
|
- Are there specific edge cases or variations to consider?
|
||||||
|
- What should be included or excluded from matches?
|
||||||
|
|
||||||
|
### Step 2: Create Example Code
|
||||||
|
|
||||||
|
Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
If searching for "async functions that use await", create a test file:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// test_example.js
|
||||||
|
async function example() {
|
||||||
|
const result = await fetchData();
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Write the ast-grep Rule
|
||||||
|
|
||||||
|
Translate the pattern into an ast-grep rule. Start simple and add complexity as needed.
|
||||||
|
|
||||||
|
**Key principles:**
|
||||||
|
- Always use `stopBy: end` for relational rules (`inside`, `has`) to ensure search goes to the end of the direction
|
||||||
|
- Use `pattern` for simple structures
|
||||||
|
- Use `kind` with `has`/`inside` for complex structures
|
||||||
|
- Break complex queries into smaller sub-rules using `all`, `any`, or `not`
|
||||||
|
|
||||||
|
**Example rule file (test_rule.yml):**
|
||||||
|
```yaml
|
||||||
|
id: async-with-await
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
See `references/rule_reference.md` for comprehensive rule documentation.
|
||||||
|
|
||||||
|
### Step 4: Test the Rule
|
||||||
|
|
||||||
|
Use ast-grep CLI to verify the rule matches the example code. There are two main approaches:
|
||||||
|
|
||||||
|
**Option A: Test with inline rules (for quick iterations)**
|
||||||
|
```bash
|
||||||
|
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules "id: test
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" --stdin
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Test with rule files (recommended for complex rules)**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --rule test_rule.yml test_example.js
|
||||||
|
```
|
||||||
|
|
||||||
|
**Debugging if no matches:**
|
||||||
|
1. Simplify the rule (remove sub-rules)
|
||||||
|
2. Add `stopBy: end` to relational rules if not present
|
||||||
|
3. Use `--debug-query` to understand the AST structure (see below)
|
||||||
|
4. Check if `kind` values are correct for the language
|
||||||
|
|
||||||
|
### Step 5: Search the Codebase
|
||||||
|
|
||||||
|
Once the rule matches the example code correctly, search the actual codebase:
|
||||||
|
|
||||||
|
**For simple pattern searches:**
|
||||||
|
```bash
|
||||||
|
ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**For complex rule-based searches:**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --rule my_rule.yml /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**For inline rules (without creating files):**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: my-rule
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: \$PATTERN" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
## ast-grep CLI Commands
|
||||||
|
|
||||||
|
### Inspect Code Structure (--debug-query)
|
||||||
|
|
||||||
|
Dump the AST structure to understand how code is parsed:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ast-grep run --pattern 'async function example() { await fetch(); }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=cst
|
||||||
|
```
|
||||||
|
|
||||||
|
**Available formats:**
|
||||||
|
- `cst`: Concrete Syntax Tree (shows all nodes including punctuation)
|
||||||
|
- `ast`: Abstract Syntax Tree (shows only named nodes)
|
||||||
|
- `pattern`: Shows how ast-grep interprets your pattern
|
||||||
|
|
||||||
|
**Use this to:**
|
||||||
|
- Find the correct `kind` values for nodes
|
||||||
|
- Understand the structure of code you want to match
|
||||||
|
- Debug why patterns aren't matching
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
# See the structure of your target code
|
||||||
|
ast-grep run --pattern 'class User { constructor() {} }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=cst
|
||||||
|
|
||||||
|
# See how ast-grep interprets your pattern
|
||||||
|
ast-grep run --pattern 'class $NAME { $$$BODY }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=pattern
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Rules (scan with --stdin)
|
||||||
|
|
||||||
|
Test a rule against code snippet without creating files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: await \$EXPR" --stdin
|
||||||
|
```
|
||||||
|
|
||||||
|
**Add --json for structured output:**
|
||||||
|
```bash
|
||||||
|
echo "const x = await fetch();" | ast-grep scan --inline-rules "..." --stdin --json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search with Patterns (run)
|
||||||
|
|
||||||
|
Simple pattern-based search for single AST node matches:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic pattern search
|
||||||
|
ast-grep run --pattern 'console.log($ARG)' --lang javascript .
|
||||||
|
|
||||||
|
# Search specific files
|
||||||
|
ast-grep run --pattern 'class $NAME' --lang python /path/to/project
|
||||||
|
|
||||||
|
# JSON output for programmatic use
|
||||||
|
ast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Simple, single-node matches
|
||||||
|
- Quick searches without complex logic
|
||||||
|
- When you don't need relational rules (inside/has)
|
||||||
|
|
||||||
|
### Search with Rules (scan)
|
||||||
|
|
||||||
|
YAML rule-based search for complex structural queries:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# With rule file
|
||||||
|
ast-grep scan --rule my_rule.yml /path/to/project
|
||||||
|
|
||||||
|
# With inline rules
|
||||||
|
ast-grep scan --inline-rules "id: find-async
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
|
||||||
|
# JSON output
|
||||||
|
ast-grep scan --rule my_rule.yml --json /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Complex structural searches
|
||||||
|
- Relational rules (inside, has, precedes, follows)
|
||||||
|
- Composite logic (all, any, not)
|
||||||
|
- When you need the power of full YAML rules
|
||||||
|
|
||||||
|
**Tip:** For relational rules (inside/has), always add `stopBy: end` to ensure complete traversal.
|
||||||
|
|
||||||
|
## Tips for Writing Effective Rules
|
||||||
|
|
||||||
|
### Always Use stopBy: end
|
||||||
|
|
||||||
|
For relational rules, always use `stopBy: end` unless there's a specific reason not to:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
This ensures the search traverses the entire subtree rather than stopping at the first non-matching node.
|
||||||
|
|
||||||
|
### Start Simple, Then Add Complexity
|
||||||
|
|
||||||
|
Begin with the simplest rule that could work:
|
||||||
|
1. Try a `pattern` first
|
||||||
|
2. If that doesn't work, try `kind` to match the node type
|
||||||
|
3. Add relational rules (`has`, `inside`) as needed
|
||||||
|
4. Combine with composite rules (`all`, `any`, `not`) for complex logic
|
||||||
|
|
||||||
|
### Use the Right Rule Type
|
||||||
|
|
||||||
|
- **Pattern**: For simple, direct code matching (e.g., `console.log($ARG)`)
|
||||||
|
- **Kind + Relational**: For complex structures (e.g., "function containing await")
|
||||||
|
- **Composite**: For logical combinations (e.g., "function with await but not in try-catch")
|
||||||
|
|
||||||
|
### Debug with AST Inspection
|
||||||
|
|
||||||
|
When rules don't match:
|
||||||
|
1. Use `--debug-query=cst` to see the actual AST structure
|
||||||
|
2. Check if metavariables are being detected correctly
|
||||||
|
3. Verify the node `kind` matches what you expect
|
||||||
|
4. Ensure relational rules are searching in the right direction
|
||||||
|
|
||||||
|
### Escaping in Inline Rules
|
||||||
|
|
||||||
|
When using `--inline-rules`, escape metavariables in shell commands:
|
||||||
|
- Use `\$VAR` instead of `$VAR` (shell interprets `$` as variable)
|
||||||
|
- Or use single quotes: `'$VAR'` works in most shells
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
# Correct: escaped $
|
||||||
|
ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" .
|
||||||
|
|
||||||
|
# Or use single quotes
|
||||||
|
ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Use Cases
|
||||||
|
|
||||||
|
### Find Functions with Specific Content
|
||||||
|
|
||||||
|
Find async functions that use await:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: async-await
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
### Find Code Inside Specific Contexts
|
||||||
|
|
||||||
|
Find console.log inside class methods:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: console-in-class
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: console.log(\$\$\$)
|
||||||
|
inside:
|
||||||
|
kind: method_definition
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
### Find Code Missing Expected Patterns
|
||||||
|
|
||||||
|
Find async functions without try-catch:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: async-no-trycatch
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end
|
||||||
|
- not:
|
||||||
|
has:
|
||||||
|
pattern: try { \$\$\$ } catch (\$E) { \$\$\$ }
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
### references/
|
||||||
|
Contains detailed documentation for ast-grep rule syntax:
|
||||||
|
- `rule_reference.md`: Comprehensive ast-grep rule documentation covering atomic rules, relational rules, composite rules, and metavariables
|
||||||
|
|
||||||
|
Load these references when detailed rule syntax information is needed.
|
||||||
@@ -0,0 +1,297 @@
|
|||||||
|
# ast-grep Rule Reference
|
||||||
|
|
||||||
|
This document provides comprehensive documentation for ast-grep rule syntax, covering all rule types and metavariables.
|
||||||
|
|
||||||
|
## Introduction to ast-grep Rules
|
||||||
|
|
||||||
|
ast-grep rules are declarative specifications for matching and filtering Abstract Syntax Tree (AST) nodes. They enable structural code search and analysis by defining conditions an AST node must meet to be matched.
|
||||||
|
|
||||||
|
### Rule Categories
|
||||||
|
|
||||||
|
ast-grep rules are categorized into three types:
|
||||||
|
|
||||||
|
* **Atomic Rules**: Match individual AST nodes based on intrinsic properties like code patterns (`pattern`), node type (`kind`), or text content (`regex`).
|
||||||
|
* **Relational Rules**: Define conditions based on a target node's position or relationship to other nodes (e.g., `inside`, `has`, `precedes`, `follows`).
|
||||||
|
* **Composite Rules**: Combine other rules using logical operations (AND, OR, NOT) to form complex matching criteria (e.g., `all`, `any`, `not`, `matches`).
|
||||||
|
|
||||||
|
## Anatomy of an ast-grep Rule Object
|
||||||
|
|
||||||
|
The ast-grep rule object is the core configuration unit defining how ast-grep identifies and filters AST nodes. It's typically written in YAML format.
|
||||||
|
|
||||||
|
### General Structure
|
||||||
|
|
||||||
|
Every field within an ast-grep Rule Object is optional, but at least one "positive" key (e.g., `kind`, `pattern`) must be present.
|
||||||
|
|
||||||
|
A node matches a rule if it satisfies all fields defined within that rule object, implying an implicit logical AND operation.
|
||||||
|
|
||||||
|
For rules using metavariables that depend on prior matching, explicit `all` composite rules are recommended to guarantee execution order.
|
||||||
|
|
||||||
|
### Rule Object Properties
|
||||||
|
|
||||||
|
| Property | Type | Category | Purpose | Example |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| `pattern` | String or Object | Atomic | Matches AST node by code pattern. | `pattern: console.log($ARG)` |
|
||||||
|
| `kind` | String | Atomic | Matches AST node by its kind name. | `kind: call_expression` |
|
||||||
|
| `regex` | String | Atomic | Matches node's text by Rust regex. | `regex: ^[a-z]+$` |
|
||||||
|
| `nthChild` | number, string, Object | Atomic | Matches nodes by their index within parent's children. | `nthChild: 1` |
|
||||||
|
| `range` | RangeObject | Atomic | Matches node by character-based start/end positions. | `range: { start: { line: 0, column: 0 }, end: { line: 0, column: 10 } }` |
|
||||||
|
| `inside` | Object | Relational | Target node must be inside node matching sub-rule. | `inside: { pattern: class $C { $$$ }, stopBy: end }` |
|
||||||
|
| `has` | Object | Relational | Target node must have descendant matching sub-rule. | `has: { pattern: await $EXPR, stopBy: end }` |
|
||||||
|
| `precedes` | Object | Relational | Target node must appear before node matching sub-rule. | `precedes: { pattern: return $VAL }` |
|
||||||
|
| `follows` | Object | Relational | Target node must appear after node matching sub-rule. | `follows: { pattern: import $M from '$P' }` |
|
||||||
|
| `all` | Array<Rule> | Composite | Matches if all sub-rules match. | `all: [ { kind: call_expression }, { pattern: foo($A) } ]` |
|
||||||
|
| `any` | Array<Rule> | Composite | Matches if any sub-rules match. | `any: [ { pattern: foo() }, { pattern: bar() } ]` |
|
||||||
|
| `not` | Object | Composite | Matches if sub-rule does not match. | `not: { pattern: console.log($ARG) }` |
|
||||||
|
| `matches` | String | Composite | Matches if predefined utility rule matches. | `matches: my-utility-rule-id` |
|
||||||
|
|
||||||
|
## Atomic Rules
|
||||||
|
|
||||||
|
Atomic rules match individual AST nodes based on their intrinsic properties.
|
||||||
|
|
||||||
|
### pattern: String and Object Forms
|
||||||
|
|
||||||
|
The `pattern` rule matches a single AST node based on a code pattern.
|
||||||
|
|
||||||
|
**String Pattern**: Directly matches using ast-grep's pattern syntax with metavariables.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Object Pattern**: Offers granular control for ambiguous patterns or specific contexts.
|
||||||
|
|
||||||
|
* `selector`: Pinpoints a specific part of the parsed pattern to match.
|
||||||
|
```yaml
|
||||||
|
pattern:
|
||||||
|
selector: field_definition
|
||||||
|
context: class { $F }
|
||||||
|
```
|
||||||
|
|
||||||
|
* `context`: Provides surrounding code context for correct parsing.
|
||||||
|
|
||||||
|
* `strictness`: Modifies the pattern's matching algorithm (`cst`, `smart`, `ast`, `relaxed`, `signature`).
|
||||||
|
```yaml
|
||||||
|
pattern:
|
||||||
|
context: foo($BAR)
|
||||||
|
strictness: relaxed
|
||||||
|
```
|
||||||
|
|
||||||
|
### kind: Matching by Node Type
|
||||||
|
|
||||||
|
The `kind` rule matches an AST node by its `tree_sitter_node_kind` name, derived from the language's Tree-sitter grammar. Useful for targeting constructs like `call_expression` or `function_declaration`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
kind: call_expression
|
||||||
|
```
|
||||||
|
|
||||||
|
### regex: Text-Based Node Matching
|
||||||
|
|
||||||
|
The `regex` rule matches the entire text content of an AST node using a Rust regular expression. It's not a "positive" rule, meaning it matches any node whose text satisfies the regex, regardless of its structural kind.
|
||||||
|
|
||||||
|
### nthChild: Positional Node Matching
|
||||||
|
|
||||||
|
The `nthChild` rule finds nodes by their 1-based index within their parent's children list, counting only named nodes by default.
|
||||||
|
|
||||||
|
* `number`: Matches the exact nth child. Example: `nthChild: 1`
|
||||||
|
* `string`: Matches positions using An+B formula. Example: `2n+1`
|
||||||
|
* `Object`: Provides granular control:
|
||||||
|
* `position`: `number` or An+B string.
|
||||||
|
* `reverse`: `true` to count from the end.
|
||||||
|
* `ofRule`: An ast-grep rule to filter the sibling list before counting.
|
||||||
|
|
||||||
|
### range: Position-Based Node Matching
|
||||||
|
|
||||||
|
The `range` rule matches an AST node based on its character-based start and end positions. A `RangeObject` defines `start` and `end` fields, each with 0-based `line` and `column`. `start` is inclusive, `end` is exclusive.
|
||||||
|
|
||||||
|
## Relational Rules
|
||||||
|
|
||||||
|
Relational rules filter targets based on their position relative to other AST nodes. They can include `stopBy` and `field` options.
|
||||||
|
|
||||||
|
### inside: Matching Within a Parent Node
|
||||||
|
|
||||||
|
Requires the target node to be inside another node matching the `inside` sub-rule.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
inside:
|
||||||
|
pattern: class $C { $$$ }
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### has: Matching with a Descendant Node
|
||||||
|
|
||||||
|
Requires the target node to have a descendant node matching the `has` sub-rule.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### precedes and follows: Sequential Node Matching
|
||||||
|
|
||||||
|
* `precedes`: Target node must appear before a node matching the `precedes` sub-rule.
|
||||||
|
* `follows`: Target node must appear after a node matching the `follows` sub-rule.
|
||||||
|
|
||||||
|
Both include `stopBy` but not `field`.
|
||||||
|
|
||||||
|
### stopBy and field: Refining Relational Searches
|
||||||
|
|
||||||
|
**stopBy**: Controls search termination for relational rules.
|
||||||
|
|
||||||
|
* `"neighbor"` (default): Stops when immediate surrounding node doesn't match.
|
||||||
|
* `"end"`: Searches to the end of the direction (root for `inside`, leaf for `has`).
|
||||||
|
* `Rule object`: Stops when a surrounding node matches the provided rule (inclusive).
|
||||||
|
|
||||||
|
**field**: Specifies a sub-node within the target node that should match the relational rule. Only for `inside` and `has`.
|
||||||
|
|
||||||
|
**Best Practice**: When unsure, always use `stopBy: end` to ensure the search goes to the end of the direction.
|
||||||
|
|
||||||
|
## Composite Rules
|
||||||
|
|
||||||
|
Composite rules combine atomic and relational rules using logical operations.
|
||||||
|
|
||||||
|
### all: Conjunction (AND) of Rules
|
||||||
|
|
||||||
|
Matches a node only if all sub-rules in the list match. Guarantees order of rule matching, important for metavariables.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
all:
|
||||||
|
- kind: call_expression
|
||||||
|
- pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### any: Disjunction (OR) of Rules
|
||||||
|
|
||||||
|
Matches a node if any sub-rules in the list match.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
any:
|
||||||
|
- pattern: console.log($ARG)
|
||||||
|
- pattern: console.warn($ARG)
|
||||||
|
- pattern: console.error($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### not: Negation (NOT) of a Rule
|
||||||
|
|
||||||
|
Matches a node if the single sub-rule does not match.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
not:
|
||||||
|
pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### matches: Rule Reuse and Utility Rules
|
||||||
|
|
||||||
|
Takes a rule-id string, matching if the referenced utility rule matches. Enables rule reuse and recursive rules.
|
||||||
|
|
||||||
|
## Metavariables
|
||||||
|
|
||||||
|
Metavariables are placeholders in patterns to match dynamic content in the AST.
|
||||||
|
|
||||||
|
### $VAR: Single Named Node Capture
|
||||||
|
|
||||||
|
Captures a single named node in the AST.
|
||||||
|
|
||||||
|
* **Valid**: `$META`, `$META_VAR`, `$_`
|
||||||
|
* **Invalid**: `$invalid`, `$123`, `$KEBAB-CASE`
|
||||||
|
* **Example**: `console.log($GREETING)` matches `console.log('Hello World')`.
|
||||||
|
* **Reuse**: `$A == $A` matches `a == a` but not `a == b`.
|
||||||
|
|
||||||
|
### $$VAR: Single Unnamed Node Capture
|
||||||
|
|
||||||
|
Captures a single unnamed node (e.g., operators, punctuation).
|
||||||
|
|
||||||
|
**Example**: To match the operator in `a + b`, use `$$OP`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
kind: binary_expression
|
||||||
|
has:
|
||||||
|
field: operator
|
||||||
|
pattern: $$OP
|
||||||
|
```
|
||||||
|
|
||||||
|
### $$$MULTI_META_VARIABLE: Multi-Node Capture
|
||||||
|
|
||||||
|
Matches zero or more AST nodes (non-greedy). Useful for variable numbers of arguments or statements.
|
||||||
|
|
||||||
|
* **Example**: `console.log($$$)` matches `console.log()`, `console.log('hello')`, and `console.log('debug:', key, value)`.
|
||||||
|
* **Example**: `function $FUNC($$$ARGS) { $$$ }` matches functions with varying parameters/statements.
|
||||||
|
|
||||||
|
### Non-Capturing Metavariables (_VAR)
|
||||||
|
|
||||||
|
Metavariables starting with an underscore (`_`) are not captured. They can match different content even if named identically, optimizing performance.
|
||||||
|
|
||||||
|
* **Example**: `$_FUNC($_FUNC)` matches `test(a)` and `testFunc(1 + 1)`.
|
||||||
|
|
||||||
|
### Important Considerations for Metavariable Detection
|
||||||
|
|
||||||
|
* **Syntax Matching**: Only exact metavariable syntax (e.g., `$A`, `$$B`, `$$$C`) is recognized.
|
||||||
|
* **Exclusive Content**: Metavariable text must be the only text within an AST node.
|
||||||
|
* **Non-working**: `obj.on$EVENT`, `"Hello $WORLD"`, `a $OP b`, `$jq`.
|
||||||
|
|
||||||
|
The ast-grep playground is useful for debugging patterns and visualizing metavariables.
|
||||||
|
|
||||||
|
## Common Patterns and Examples
|
||||||
|
|
||||||
|
### Finding Functions with Specific Content
|
||||||
|
|
||||||
|
Find functions that contain await expressions:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Finding Code Inside Specific Contexts
|
||||||
|
|
||||||
|
Find console.log calls inside class methods:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
pattern: console.log($$$)
|
||||||
|
inside:
|
||||||
|
kind: method_definition
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Combining Multiple Conditions
|
||||||
|
|
||||||
|
Find async functions that use await but don't have try-catch:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
- not:
|
||||||
|
has:
|
||||||
|
pattern: try { $$$ } catch ($E) { $$$ }
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Matching Multiple Alternatives
|
||||||
|
|
||||||
|
Find any type of console method call:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
any:
|
||||||
|
- pattern: console.log($$$)
|
||||||
|
- pattern: console.warn($$$)
|
||||||
|
- pattern: console.error($$$)
|
||||||
|
- pattern: console.debug($$$)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting Tips
|
||||||
|
|
||||||
|
1. **Rule doesn't match**: Use `dump_syntax_tree` to see the actual AST structure
|
||||||
|
2. **Relational rule issues**: Ensure `stopBy: end` is set for deep searches
|
||||||
|
3. **Wrong node kind**: Check the language's Tree-sitter grammar for correct kind names
|
||||||
|
4. **Metavariable not working**: Ensure it's the only content in its AST node
|
||||||
|
5. **Pattern too complex**: Break it down into simpler sub-rules using `all`
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
name: code-changes
|
||||||
|
description: >
|
||||||
|
Orchestration workflow for any task that ends in code changes: issue analysis, pull request
|
||||||
|
review, feature implementation, bug fixes, refactors, or fleshing out an idea. MUST be invoked
|
||||||
|
at the start of such a task, before reading or writing any code. Defines how to analyze first,
|
||||||
|
gate on user approval, plan, pick the right executor model, delegate and supervise subagents,
|
||||||
|
verify, and deliver.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Code Changes
|
||||||
|
|
||||||
|
The workflow for going from an issue, pull request, idea, or feature request to shipped code.
|
||||||
|
Follow the phases in order. Analysis always comes first; code comes last.
|
||||||
|
|
||||||
|
Each phase has a reference file with the full instructions. **Read the reference file when you
|
||||||
|
enter the phase** — not before, and never skip it because the phase "looks obvious".
|
||||||
|
|
||||||
|
## Roles
|
||||||
|
|
||||||
|
Assign work based on model capability. The coordinator is not the strongest model — it's the one
|
||||||
|
that stays resident, owns every phase by default, and knows when it's out of its depth.
|
||||||
|
|
||||||
|
| Role | Capability tier | Owns |
|
||||||
|
| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||||
|
| Coordinator | Capable mid-tier, resident for the whole task | Analysis, plan, delegation, supervision, verification, delivery — by default |
|
||||||
|
| Escalation | Strongest reasoning model available; invoked only on trigger | The specific judgment call the coordinator flagged, then control returns |
|
||||||
|
| Implementer | Same tier as coordinator, or smaller for trivial edits | Executing one pinned, self-contained task |
|
||||||
|
|
||||||
|
Concrete model names per vendor (Anthropic, OpenAI, Google) and how to run the split in Claude
|
||||||
|
Code, GitHub Copilot, Codex, or IDE agents: [references/model-tiers.md](references/model-tiers.md).
|
||||||
|
|
||||||
|
When the current agent already runs at implementer tier, there's no separate delegation step for
|
||||||
|
standard work: plan and execute directly, still following every phase. Escalate to the strongest
|
||||||
|
model only when a trigger fires — see [references/escalate.md](references/escalate.md) — never by
|
||||||
|
default and never for a routine judgment call the coordinator is equipped to make itself.
|
||||||
|
|
||||||
|
## The flow
|
||||||
|
|
||||||
|
1. **Analyze** ([references/analyze.md](references/analyze.md)) — root cause and scope,
|
||||||
|
validated against the code, never against the report alone.
|
||||||
|
2. **Plan** ([references/plan.md](references/plan.md)) — pinned spec, task split, parallel vs
|
||||||
|
sequential, workspace per task.
|
||||||
|
3. **Delegate** ([references/delegate.md](references/delegate.md)) — match each task to the
|
||||||
|
right executor, coordinator-tier by default.
|
||||||
|
4. **Supervise** ([references/supervise.md](references/supervise.md)) — monitor, unblock, and
|
||||||
|
critically review implementer output.
|
||||||
|
5. **Verify** ([references/verify.md](references/verify.md)) — quality gates plus functional
|
||||||
|
proof, never delegated downward.
|
||||||
|
6. **Deliver** ([references/deliver.md](references/deliver.md)) — conventional commits and an
|
||||||
|
outcome-first report.
|
||||||
|
|
||||||
|
Analyze, Supervise, and Verify each carry an escalation checkpoint — see
|
||||||
|
[references/escalate.md](references/escalate.md) — for handing one specific judgment call to the
|
||||||
|
strongest available model without giving up ownership of the phase.
|
||||||
|
|
||||||
|
**Stop gate:** Phase 1 ends with reporting the analysis and proposed approach to the user and
|
||||||
|
waiting for a go. Skip the gate only when the user already gave the go in the request itself
|
||||||
|
("do it", "fix it and commit", "implement with Sonnet").
|
||||||
|
|
||||||
|
## Special cases
|
||||||
|
|
||||||
|
These entry points replace or extend Phase 1; the rest of the flow applies unchanged.
|
||||||
|
|
||||||
|
- Pull request review comments →
|
||||||
|
[references/pr-review-comments.md](references/pr-review-comments.md)
|
||||||
|
- Issue triage → [references/issue-triage.md](references/issue-triage.md)
|
||||||
@@ -0,0 +1,49 @@
|
|||||||
|
# Phase 1 — Analyze
|
||||||
|
|
||||||
|
Start every task here, no matter how it arrived: issue link, PR number, verbal idea, bug report.
|
||||||
|
No code gets written or edited during this phase.
|
||||||
|
|
||||||
|
## Gather the full context
|
||||||
|
|
||||||
|
- Issues and PRs: `gh issue view <n> --comments` / `gh pr view <n> --comments`, plus linked
|
||||||
|
issues, referenced discussions, and any code the report points at.
|
||||||
|
- Ideas and verbal requests: restate the goal and constraints in your own words. If the request
|
||||||
|
is ambiguous, resolve the ambiguity now — not halfway through implementation.
|
||||||
|
- Check for prior art: existing helpers, similar segments/modules, and past commits that touched
|
||||||
|
the same area (`git log -- <path>`).
|
||||||
|
|
||||||
|
## Reproduce before theorizing
|
||||||
|
|
||||||
|
Reproduce the problem when possible. A reproduction turns the analysis from a hypothesis into a
|
||||||
|
fact and gives Phase 5 its verification case for free. When reproduction is impossible (platform,
|
||||||
|
hardware, credentials), say so explicitly in the report and mark the fix as unverified-by-repro.
|
||||||
|
|
||||||
|
## Find the root cause in the code
|
||||||
|
|
||||||
|
- Read the actual implementation. Never reason from the issue text, a review comment, or a stack
|
||||||
|
trace alone — reports and bot reviewers are frequently wrong.
|
||||||
|
- Distinguish the root cause from the symptom. Fixing where it crashes is not the same as fixing
|
||||||
|
why it crashes.
|
||||||
|
- State what the change should be, which files it touches, and what it deliberately leaves alone.
|
||||||
|
|
||||||
|
## When to escalate
|
||||||
|
|
||||||
|
If root cause can't be pinned with confidence, or the fix looks architectural, security-sensitive,
|
||||||
|
or irreversible, hand the specific question to the strongest available model instead of guessing —
|
||||||
|
see [references/escalate.md](references/escalate.md). Resume ownership of the phase once the
|
||||||
|
question is answered.
|
||||||
|
|
||||||
|
## Output of this phase
|
||||||
|
|
||||||
|
A short analysis report to the user containing:
|
||||||
|
|
||||||
|
1. What is actually happening and why (root cause, with file references).
|
||||||
|
2. The proposed change and its scope.
|
||||||
|
3. What is intentionally out of scope.
|
||||||
|
4. Open questions, if any remain.
|
||||||
|
|
||||||
|
## Stop gate
|
||||||
|
|
||||||
|
Report the analysis and wait for a go before implementing. Skip the gate only when the user
|
||||||
|
already gave the go in the request itself ("do it", "fix it and commit", "implement with
|
||||||
|
Sonnet"). A go given for analysis is not a go for implementation.
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
# Phase 3 — Delegate
|
||||||
|
|
||||||
|
Match the executor to the task, not the other way around. The point is cost and speed without
|
||||||
|
losing quality — the coordinator stays accountable for the result.
|
||||||
|
|
||||||
|
## Executor matrix
|
||||||
|
|
||||||
|
Tier definitions and per-vendor model examples: [model-tiers.md](model-tiers.md).
|
||||||
|
|
||||||
|
| Task profile | Executor |
|
||||||
|
| ---------------------------------------------------------- | ------------------------------------------------------------ |
|
||||||
|
| Trivial: mechanical edit, config tweak, typo, doc update | Do it directly, or batch on a trivial-tier model |
|
||||||
|
| Standard, well-specified implementation | Coordinator itself, or a same-tier subagent for parallelism |
|
||||||
|
| Hits an escalation trigger (see [escalate.md](escalate.md)) | Escalation-tier subagent, for that one specific question |
|
||||||
|
|
||||||
|
- The coordinator typically runs at implementer tier itself, so standard tasks are usually
|
||||||
|
executed directly rather than delegated. Delegate anyway when there's real parallelism —
|
||||||
|
independent tasks, each in its own worktree — or to shed trivial mechanical work onto a
|
||||||
|
cheaper model.
|
||||||
|
- Escalation is never the default path for "ambiguous" or "architectural" — it fires only on the
|
||||||
|
concrete triggers in [escalate.md](escalate.md), and only for the specific question, not the
|
||||||
|
whole task.
|
||||||
|
|
||||||
|
## What a delegation carries
|
||||||
|
|
||||||
|
Hand the subagent its full pinned spec from Phase 2, plus:
|
||||||
|
|
||||||
|
- The verification commands it must run and pass before reporting done.
|
||||||
|
- The instruction to report what it changed and what it verified — not just "done".
|
||||||
|
- The instruction to stop and report when it hits something the spec does not cover, instead of
|
||||||
|
improvising scope.
|
||||||
|
|
||||||
|
## What is never delegated downward
|
||||||
|
|
||||||
|
Analysis, final verification, and delivery never go to an implementer — they stay with the
|
||||||
|
coordinator or go up to Escalation tier for a specific question:
|
||||||
|
|
||||||
|
- Analysis and root-cause work (Phase 1).
|
||||||
|
- Final verification (Phase 5) — an implementer's green run is a claim, not a result.
|
||||||
|
- Commits, history rewrites, pushes, and user-facing reporting (Phase 6) — these stay with the
|
||||||
|
coordinator regardless of tier; they're about accountability, not capability, so they never go
|
||||||
|
to Escalation tier either.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Phase 6 — Deliver
|
||||||
|
|
||||||
|
The change is verified; now package it.
|
||||||
|
|
||||||
|
## Commits
|
||||||
|
|
||||||
|
- Use the conventional-commit skill for every commit message.
|
||||||
|
- One logical unit per commit. A feature and its lint fallout can be separate commits when they
|
||||||
|
answer different "why"s.
|
||||||
|
- Stage files explicitly — never `git add -A`.
|
||||||
|
- Review the staged diff before committing, especially after auto-fixing tools rewrote files.
|
||||||
|
|
||||||
|
## Push and PR policy
|
||||||
|
|
||||||
|
Do not push, force-push, or open a PR unless the user asked for it. "Commit" means commit;
|
||||||
|
nothing more. When a push is asked for on a rewritten branch, use `--force-with-lease`.
|
||||||
|
|
||||||
|
## The final report
|
||||||
|
|
||||||
|
Outcome first, then evidence. It contains:
|
||||||
|
|
||||||
|
1. What changed, with clickable file references, and why — one paragraph before any detail.
|
||||||
|
2. Where implementer output was overridden, and the reason.
|
||||||
|
3. Verification evidence: the gates that ran and the concrete functional results observed.
|
||||||
|
4. Loose ends explicitly left to the user (secrets to delete, manual validation steps, decisions
|
||||||
|
deferred), each with the exact command or check when applicable.
|
||||||
|
|
||||||
|
Never report an unverified step as done, and never bury a failure in the middle of a success
|
||||||
|
story.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Escalation triggers
|
||||||
|
|
||||||
|
The coordinator owns every phase by default. Escalation is a bounded subagent call to the
|
||||||
|
strongest available model for one specific judgment call — not a handoff of the phase. The
|
||||||
|
coordinator frames the question, gets the answer, and stays the one accountable for the result.
|
||||||
|
|
||||||
|
Escalate when one of these is actually true, not on a general feeling that the task is hard:
|
||||||
|
|
||||||
|
- Root cause can't be pinned with confidence after actually reading the code — not after
|
||||||
|
re-reading the report again.
|
||||||
|
- The change is architectural: it crosses a module boundary, touches a public API/interface, or
|
||||||
|
introduces a cross-cutting abstraction.
|
||||||
|
- The code is security-, auth-, crypto-, payments-, or data-migration-sensitive.
|
||||||
|
- The operation is irreversible or high-blast-radius (schema migration, deletion, force-push,
|
||||||
|
production config).
|
||||||
|
- An implementer has reported a spec gap or contradiction more than once on the same task.
|
||||||
|
- Reviewing a diff leaves the coordinator unsure whether the fix is correct or merely plausible.
|
||||||
|
- The user explicitly asked for a second opinion or an adversarial review.
|
||||||
|
|
||||||
|
None of these fire on routine work. Most tasks should complete without ever calling Escalation
|
||||||
|
tier — the coordinator is capable enough to do the analysis, review, and verification itself, and
|
||||||
|
the strongest model gets paid for only on the calls that actually need it.
|
||||||
|
|
||||||
|
## How to escalate
|
||||||
|
|
||||||
|
Frame the specific question, not the whole task. Hand over the pinned context needed to answer
|
||||||
|
it — the relevant code, the hypothesis so far, why it's uncertain — get the answer, and resume
|
||||||
|
the phase. Escalation never becomes the new owner of the task, and it never decides scope; it
|
||||||
|
answers the question it was asked and returns control to the coordinator.
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
# Special case — Issue triage
|
||||||
|
|
||||||
|
Entry point when the task is "look at issue #n". This is Phase 1 with a sharper deliverable:
|
||||||
|
the analysis itself is the product; implementation only happens on an explicit go.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. `gh issue view <n> --comments` — read the full report, every comment, and linked issues.
|
||||||
|
2. Reproduce the reported behavior. When reproduction needs an environment you lack (OS, shell,
|
||||||
|
font, hardware), state that and reason from the code instead — flagged as such.
|
||||||
|
3. Locate the root cause in the code, not in the issue text. Issue reports describe symptoms and
|
||||||
|
often guess wrong about causes.
|
||||||
|
4. Assess blast radius: who else is affected, since when (which release or commit introduced
|
||||||
|
it), and whether workarounds exist.
|
||||||
|
|
||||||
|
## Deliverable
|
||||||
|
|
||||||
|
An analysis report to the user:
|
||||||
|
|
||||||
|
1. Confirmed or could-not-reproduce, with evidence.
|
||||||
|
2. Root cause, with file references.
|
||||||
|
3. Proposed fix and its scope, or the reason no fix is warranted (works-as-intended, duplicate,
|
||||||
|
environment problem).
|
||||||
|
4. Suggested reply to the issue when the finding should be communicated upstream.
|
||||||
|
|
||||||
|
## Gate
|
||||||
|
|
||||||
|
This is the Phase 1 stop gate: implement only on go, then continue from Phase 2.
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# Model tiers and agent tooling
|
||||||
|
|
||||||
|
The workflow talks about capability tiers, not vendor names. Map whatever stack is in use onto
|
||||||
|
these four tiers. The model names below are a mid-2026 snapshot — they go stale; when a name no
|
||||||
|
longer exists, map its replacement by tier, not by nostalgia.
|
||||||
|
|
||||||
|
## The four tiers
|
||||||
|
|
||||||
|
| Tier | Role | Anthropic | OpenAI | Google |
|
||||||
|
| ----------- | ------------------------------------------- | ----------------- | ----------------- | ----------------- |
|
||||||
|
| Escalation | Judgment calls the coordinator flags | Fable 5, Opus 4.8 | Sol, GPT-5 (high) | Gemini 2.5 Pro |
|
||||||
|
| Coordinator | Resident; owns every phase by default | Sonnet 5 | GPT-5, GPT-4.1 | Gemini 2.5 Flash |
|
||||||
|
| Implementer | Pinned-spec work, often same tier as coordinator | Sonnet 5 | GPT-5, GPT-4.1 | Gemini 2.5 Flash |
|
||||||
|
| Trivial | Mechanical edits | Haiku 4.5 | GPT-4.1 mini | Gemini Flash-Lite |
|
||||||
|
|
||||||
|
- **Escalation** — the strongest reasoning model available, called only when a trigger in
|
||||||
|
[escalate.md](escalate.md) fires: unclear root cause, architectural risk, security sensitivity,
|
||||||
|
an irreversible operation, repeated spec gaps, or low confidence in a review. Answers one
|
||||||
|
specific question, then hands control back to the coordinator.
|
||||||
|
- **Coordinator** — a capable mid-tier model, resident for the whole task. Owns analysis,
|
||||||
|
planning, supervision, and verification by default. It's capable enough for the large majority
|
||||||
|
of work, and cheap enough relative to Escalation tier that most tasks never need to call up at
|
||||||
|
all — that's the point of the split.
|
||||||
|
- **Implementer** — often literally the same model as the coordinator; the distinction is
|
||||||
|
parallelism and workspace isolation, not capability. Falls back to a smaller model for batches
|
||||||
|
of mechanical, unambiguous edits.
|
||||||
|
- **Trivial** — small, very fast models for mechanical, unambiguous edits: renames, config
|
||||||
|
tweaks, typo fixes, doc touch-ups. Batch several to amortize the dispatch overhead. When in
|
||||||
|
doubt between trivial and implementer, pick implementer — a wrong cheap edit costs more than
|
||||||
|
the price difference.
|
||||||
|
|
||||||
|
## Tooling mappings
|
||||||
|
|
||||||
|
How to run the coordinator/escalation/implementer split in common agent tooling:
|
||||||
|
|
||||||
|
- **Claude Code** — run the session itself on a coordinator-tier model (e.g. Sonnet 5). Call
|
||||||
|
`Agent` with `model: opus` (or `fable`) only at an escalation checkpoint, scoped to the one
|
||||||
|
question that triggered it. Use worktree isolation for parallel implementer-tier tasks, and
|
||||||
|
`model: haiku` for batched trivial edits.
|
||||||
|
- **GitHub Copilot** — run Copilot Chat on a coordinator-tier model for the whole flow; switch the
|
||||||
|
model picker to the strongest reasoning model only for the specific question an escalation
|
||||||
|
trigger flagged, then switch back. Standalone, well-specified tasks can still be assigned to the
|
||||||
|
Copilot coding agent (assign the issue or PR to Copilot), which works on its own branch — the
|
||||||
|
pinned spec becomes the issue body.
|
||||||
|
- **Codex** — orchestrate locally (CLI or chat) on a coordinator-tier model; dispatch each pinned
|
||||||
|
spec as a Codex cloud task, one task per independent unit, and review the resulting diffs
|
||||||
|
yourself, escalating to the frontier model only when a trigger fires.
|
||||||
|
- **Cursor and similar IDE agents** — one composer/agent session per task on a coordinator-tier
|
||||||
|
model; background agents for the parallel implementer-tier ones; switch to the strongest model
|
||||||
|
in-session only for an escalation checkpoint, then switch back.
|
||||||
|
|
||||||
|
**No subagent support at all?** Keep the phases, drop the parallelism: run the whole flow on a
|
||||||
|
coordinator-tier model, and switch the session model up to the strongest one only for the specific
|
||||||
|
question an escalation trigger flagged, then switch back down. The discipline transfers even when
|
||||||
|
the delegation mechanism does not.
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
# Phase 2 — Plan
|
||||||
|
|
||||||
|
Turn the approved analysis into an executable plan. The quality bar: an implementer-tier model
|
||||||
|
must be able to execute each task without asking questions.
|
||||||
|
|
||||||
|
## Pin the spec
|
||||||
|
|
||||||
|
Write the spec down before delegating anything. It contains:
|
||||||
|
|
||||||
|
- The decided approach — including decisions already made, so the implementer does not relitigate
|
||||||
|
them.
|
||||||
|
- Files to touch, and the entry points to start from.
|
||||||
|
- Constraints: style rules, patterns to follow (point at existing code), performance or
|
||||||
|
compatibility requirements.
|
||||||
|
- Verification commands the implementer must run locally (build, tests, lint).
|
||||||
|
- Explicit non-goals: what the task must NOT change. This is what keeps subagents from wandering.
|
||||||
|
|
||||||
|
## Split into tasks
|
||||||
|
|
||||||
|
- One task = one self-contained unit an implementer can finish and verify on its own.
|
||||||
|
- Mark which tasks are independent and which consume another task's output. Parallelize the
|
||||||
|
independent ones; sequence the rest. When in doubt, sequence — a merge conflict between two
|
||||||
|
parallel subagents costs more than the parallelism saves.
|
||||||
|
- Documentation updates belong to the task that changes the behavior, not to a separate task.
|
||||||
|
|
||||||
|
## Decide the workspace per task
|
||||||
|
|
||||||
|
- Main working tree: when the task depends on uncommitted local changes, or when you will review
|
||||||
|
and commit the result in the current session.
|
||||||
|
- Isolated worktree: everything else, especially parallel tasks — they must never share a
|
||||||
|
working tree.
|
||||||
|
|
||||||
|
## Output of this phase
|
||||||
|
|
||||||
|
A task list where each entry names its executor tier (see Phase 3), its workspace, its
|
||||||
|
dependencies, and carries its pinned spec.
|
||||||
@@ -0,0 +1,35 @@
|
|||||||
|
# Special case — Pull request review comments
|
||||||
|
|
||||||
|
Entry point when the task is "handle the review comments on PR #n". This replaces Phase 1's
|
||||||
|
issue analysis; Phases 2–6 apply unchanged.
|
||||||
|
|
||||||
|
## Validate before touching anything
|
||||||
|
|
||||||
|
- Fetch every unresolved comment (`gh pr view <n> --comments`, or the review threads via
|
||||||
|
`gh api`).
|
||||||
|
- Validate each comment against the actual code before changing anything. Classify it as valid
|
||||||
|
or invalid. Automated reviewers (Copilot and friends) regularly flag non-issues — treat their
|
||||||
|
comments as leads, not verdicts.
|
||||||
|
|
||||||
|
## Valid comments
|
||||||
|
|
||||||
|
- Fix the issue folded into the commit that owns the code: `git commit --fixup <sha>`, then
|
||||||
|
`git rebase --autosquash`.
|
||||||
|
- Confirm the rewritten tree is byte-identical to the pre-rebase tree plus the intended fix
|
||||||
|
(`git diff` between old and new tip). A fixup that changes anything else went to the wrong
|
||||||
|
commit.
|
||||||
|
- Run the quality gates (Phase 5) before rewriting history, not after.
|
||||||
|
- Force-push with `--force-with-lease`.
|
||||||
|
|
||||||
|
## Invalid comments
|
||||||
|
|
||||||
|
- Do not change code to appease a wrong comment.
|
||||||
|
- Reply with the evidence that refutes it: the code path, the existing test, the verified
|
||||||
|
behavior. Specific beats polite-but-vague.
|
||||||
|
- When a comment is wrong but exposes something genuinely confusing, harden the code or comment
|
||||||
|
against the misreading instead — and say so in the reply.
|
||||||
|
|
||||||
|
## Reply to every thread
|
||||||
|
|
||||||
|
Each thread gets a reply describing what was done and how it was verified. Leave resolving the
|
||||||
|
threads to the humans.
|
||||||
@@ -0,0 +1,35 @@
|
|||||||
|
# Phase 4 — Supervise
|
||||||
|
|
||||||
|
Delegation is not fire-and-forget. The coordinator tracks delivery and owns the outcome.
|
||||||
|
|
||||||
|
## Monitor and unblock
|
||||||
|
|
||||||
|
- Track each subagent's progress against its spec.
|
||||||
|
- When a subagent stalls or loops on a problem: stop it, diagnose the problem yourself, hand it
|
||||||
|
the answer, and let it proceed. Do not let it burn turns rediscovering what you already know.
|
||||||
|
- When a subagent reports a spec gap, decide — update the spec or cut the scope — and send it
|
||||||
|
back with the decision. Never let it decide scope on its own.
|
||||||
|
|
||||||
|
## Review the output critically
|
||||||
|
|
||||||
|
Review every subagent diff as if it were an external PR:
|
||||||
|
|
||||||
|
- Check the diff against the spec: everything asked for, nothing beyond it.
|
||||||
|
- Override solutions that are wrong or overbuilt. Prefer the change that removes code over the
|
||||||
|
one that adds it. It is normal to keep a subagent's diagnosis but replace its fix with a
|
||||||
|
simpler one — document the override and its reason for the final report.
|
||||||
|
- Watch for spec-compliant-but-ugly: a change can satisfy the letter of the spec and still not
|
||||||
|
belong in the codebase. Consistency with surrounding code wins.
|
||||||
|
|
||||||
|
## Escalate on low confidence
|
||||||
|
|
||||||
|
If a diff leaves you unsure whether the fix is correct or merely plausible, or it touches
|
||||||
|
security, data-migration, or otherwise irreversible territory, get a second read from the
|
||||||
|
strongest available model before signing off — see
|
||||||
|
[references/escalate.md](references/escalate.md). Don't rubber-stamp a diff you can't fully
|
||||||
|
verify yourself.
|
||||||
|
|
||||||
|
## Trust nothing unverified
|
||||||
|
|
||||||
|
"Tests pass" from a subagent is a claim, not a result. Phase 5 re-verifies everything
|
||||||
|
independently, on the merged state — not per-task.
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
# Phase 5 — Verify
|
||||||
|
|
||||||
|
Verification is never delegated downward and runs on the final, merged state of the change. It
|
||||||
|
has two halves: the project's quality gates, and functional proof. Both are the coordinator's own
|
||||||
|
work by default.
|
||||||
|
|
||||||
|
## Quality gates
|
||||||
|
|
||||||
|
- Build, full test suite, formatters, and linters — all must pass with zero errors.
|
||||||
|
- Apply the project's language skill when one exists (for example the Go skill's pre-commit
|
||||||
|
gate: `modernize`, `fieldalignment`, `go mod tidy`, `gofmt`, `golangci-lint`).
|
||||||
|
- Cross-compile when platform-specific files changed (`_windows.go`, `_unix.go`, and the like) —
|
||||||
|
the local OS linter skips the other platform's rules.
|
||||||
|
|
||||||
|
## Functional proof
|
||||||
|
|
||||||
|
Tests passing is necessary, not sufficient. Run the real flow and confirm concrete outputs:
|
||||||
|
render the prompt, execute the command, hit the endpoint. Record the actual values observed —
|
||||||
|
the final report quotes them as evidence, not adjectives.
|
||||||
|
|
||||||
|
When the user said they will do the manual validation, state exactly what they should check and
|
||||||
|
what the expected result is.
|
||||||
|
|
||||||
|
## Escalate on high-stakes results
|
||||||
|
|
||||||
|
Running the gates and the functional proof stays with the coordinator. If the result is
|
||||||
|
ambiguous, or the change is high-blast-radius (migrations, security, irreversible operations), get
|
||||||
|
the strongest available model to judge the evidence before declaring done — see
|
||||||
|
[references/escalate.md](references/escalate.md).
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Documentation changes ship in the same change as the code they describe. Check for every
|
||||||
|
user-visible behavior change:
|
||||||
|
|
||||||
|
- Project docs / website pages for the touched feature.
|
||||||
|
- README or setup instructions when flags, commands, or defaults changed.
|
||||||
|
|
||||||
|
## On failure
|
||||||
|
|
||||||
|
A failed gate or a wrong functional result sends the task back to Phase 4 (fix via the
|
||||||
|
implementer) or Phase 1 (the analysis was wrong). Never weaken a gate, skip a linter, or delete
|
||||||
|
a test to get to green.
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
---
|
||||||
|
name: conventional-commit
|
||||||
|
description: >
|
||||||
|
Workflow for generating conventional commit messages following the Conventional Commits
|
||||||
|
specification. MUST be invoked every time a commit is created. Guides construction of
|
||||||
|
standardized commit messages with correct type, scope, description, body, and footer.
|
||||||
|
triggers:
|
||||||
|
- on_commit
|
||||||
|
---
|
||||||
|
|
||||||
|
# Conventional Commit
|
||||||
|
|
||||||
|
## Commit Message Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
<type>(<scope>): <description>
|
||||||
|
|
||||||
|
[optional body]
|
||||||
|
|
||||||
|
[optional footer(s)]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Types
|
||||||
|
|
||||||
|
| Type | When to use |
|
||||||
|
| ---------- | ------------------------------------------------------ |
|
||||||
|
| `feat` | A new feature |
|
||||||
|
| `fix` | A bug fix |
|
||||||
|
| `docs` | Documentation changes, no code |
|
||||||
|
| `style` | Formatting, missing semicolons, etc. (no logic change) |
|
||||||
|
| `refactor` | Code change that is neither a fix nor a feature |
|
||||||
|
| `perf` | Performance improvement |
|
||||||
|
| `test` | Adding or correcting tests |
|
||||||
|
| `ci` | CI configuration changes |
|
||||||
|
| `chore` | Maintenance tasks (updating deps, tooling, etc.) |
|
||||||
|
| `revert` | Reverts a previous commit |
|
||||||
|
|
||||||
|
Append `!` after the type/scope to signal a **breaking change**: `feat!:` or `feat(api)!:`
|
||||||
|
When a change breaks existing behavior, **both markers are mandatory**: the `!` suffix on the type
|
||||||
|
**and** the `BREAKING CHANGE:` footer. They always appear together — never one without the other.
|
||||||
|
|
||||||
|
### Scope
|
||||||
|
|
||||||
|
Optional. Use the name of the area affected, e.g., `segment`, `cache`, `config`, `ui`.
|
||||||
|
Omit when the change is truly cross-cutting.
|
||||||
|
|
||||||
|
### Description
|
||||||
|
|
||||||
|
- Required. One short imperative sentence, no period at the end. The full header line (type +
|
||||||
|
scope + description) must be **72 characters or fewer**. Aim for **50 characters or fewer for
|
||||||
|
the description itself** — this almost always keeps the full header within budget regardless
|
||||||
|
of type and scope length.
|
||||||
|
- Use the imperative mood: "add", not "added" or "adds". Never past tense or present-third-person:
|
||||||
|
✗ `added`, `fixed`, `bumped`, `implemented` → ✓ `add`, `fix`, `bump`, `implement`.
|
||||||
|
- **Never mirror the input's phrasing.** If the request uses past-tense words (`updated`, `added`,
|
||||||
|
`bumped`, `was removed`, `got regenerated`), convert them to imperative before writing the
|
||||||
|
description: `update`, `add`, `bump`, `remove`, `regenerate`.
|
||||||
|
|
||||||
|
### Body
|
||||||
|
|
||||||
|
Optional. Add context about _why_ the change was made, not _what_. The diff shows that.
|
||||||
|
Wrap at 72 characters.
|
||||||
|
|
||||||
|
### Footer
|
||||||
|
|
||||||
|
Use for:
|
||||||
|
|
||||||
|
- `BREAKING CHANGE: <description>` (required when `!` is used; explains the break).
|
||||||
|
- Issue references: `Closes #123`, `Fixes #456`.
|
||||||
|
- Co-authors: `Co-Authored-By: Name <email>`.
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
1. Run `git status` to review changed files.
|
||||||
|
2. Run `git diff` and `git diff --cached` to inspect staged and unstaged changes.
|
||||||
|
3. Identify the **type** from the table above. Ask yourself: does this change **remove, rename, or
|
||||||
|
alter existing behavior** that callers depend on? If yes → it is a breaking change: use `!`
|
||||||
|
after the type/scope **and** add a `BREAKING CHANGE:` footer. Both markers are always required
|
||||||
|
together.
|
||||||
|
4. Identify the **scope** from the files/area changed.
|
||||||
|
5. Write a short **description** in the imperative mood.
|
||||||
|
6. Add a **body** if the _why_ needs explanation.
|
||||||
|
7. Add a **footer** for breaking changes or issue references.
|
||||||
|
8. Stage the relevant files explicitly (avoid `git add -A`).
|
||||||
|
9. Commit with a message that preserves multi-line formatting when body/footer are present.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
```text
|
||||||
|
feat(segment): add Ramadan segment with Aladhan API
|
||||||
|
fix(cache): always store mod time
|
||||||
|
docs(readme): update installation instructions
|
||||||
|
refactor(config): simplify option parsing logic
|
||||||
|
chore(deps): bump github.com/shirou/gopsutil/v4
|
||||||
|
feat(segment)!: rename template property StartTime to Start
|
||||||
|
|
||||||
|
BREAKING CHANGE: template strings using .StartTime must be updated to .Start
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validation Checklist
|
||||||
|
|
||||||
|
- [ ] Type is one of the allowed values in .commitlintrc.yml
|
||||||
|
- [ ] The commit message respects the rules defined in .commitlintrc.yml
|
||||||
|
- [ ] Scope (if present) reflects the actual area changed
|
||||||
|
- [ ] Description is imperative mood, no trailing period
|
||||||
|
- [ ] Full header line (type + scope + description) is 72 characters or fewer
|
||||||
|
- [ ] Both `!` after type/scope **and** `BREAKING CHANGE:` footer are present whenever the change breaks existing behavior
|
||||||
|
- [ ] No sensitive files staged (.env, credentials, etc.)
|
||||||
@@ -0,0 +1,485 @@
|
|||||||
|
---
|
||||||
|
name: golang
|
||||||
|
description: >
|
||||||
|
Go coding standards and conventions for this project. Apply when writing,
|
||||||
|
reviewing, or refactoring any Go source file.
|
||||||
|
triggers:
|
||||||
|
- on_commit
|
||||||
|
---
|
||||||
|
|
||||||
|
# Go Development Instructions
|
||||||
|
|
||||||
|
Follow idiomatic Go practices and community standards when writing Go code.
|
||||||
|
These instructions are based on [Effective Go](https://go.dev/doc/effective_go),
|
||||||
|
[Go Code Review Comments](https://go.dev/wiki/CodeReviewComments),
|
||||||
|
and [Google's Go Style Guide](https://google.github.io/styleguide/go/).
|
||||||
|
|
||||||
|
## General Instructions
|
||||||
|
|
||||||
|
- Write simple, clear, and idiomatic Go code
|
||||||
|
- Favor clarity and simplicity over cleverness
|
||||||
|
- Follow the principle of least surprise
|
||||||
|
- Keep the happy path left-aligned (reduce indentation)
|
||||||
|
- Return early to reduce nesting
|
||||||
|
- Make the zero value useful
|
||||||
|
- Document exported types, functions, methods, and packages
|
||||||
|
- Use Go modules for dependency management
|
||||||
|
- **AVOID `else` statements - use early returns, continue, or break instead**
|
||||||
|
- Avoid wrapping primitives without a clear semantic benefit; define new types when they add meaning.
|
||||||
|
- Use typed slices/maps and document element semantics when not obvious.
|
||||||
|
- Start error strings with a lowercase letter.
|
||||||
|
|
||||||
|
## Naming Conventions
|
||||||
|
|
||||||
|
### Packages
|
||||||
|
|
||||||
|
- Use lowercase, single-word package names
|
||||||
|
- Avoid `_` characters, hyphens, or mixedCaps
|
||||||
|
- Choose names that describe what the package provides, not what it contains
|
||||||
|
- Avoid generic names like `util`, `common`, or `base`
|
||||||
|
- Package names should be singular, not plural
|
||||||
|
|
||||||
|
### Variables and Functions
|
||||||
|
|
||||||
|
- Use mixedCaps or MixedCaps (camelCase) rather than `_` characters
|
||||||
|
- Keep names short but descriptive
|
||||||
|
- Use single-letter variables for very short scopes (like loop indices)
|
||||||
|
- Exported names start with a capital letter
|
||||||
|
- Unexported names start with a lowercase letter
|
||||||
|
- Avoid stuttering (e.g., avoid `http.HTTPServer`, prefer `http.Server`)
|
||||||
|
|
||||||
|
### Interfaces
|
||||||
|
|
||||||
|
- Name interfaces with -er suffix when possible (e.g., `Reader`, `Writer`, `Formatter`)
|
||||||
|
- Single-method interfaces should be named after the method (e.g., `Read` → `Reader`)
|
||||||
|
- Keep interfaces small and focused
|
||||||
|
|
||||||
|
### Constants
|
||||||
|
|
||||||
|
- Use MixedCaps for exported constants
|
||||||
|
- Use mixedCaps for unexported constants
|
||||||
|
- Group related constants using `const` blocks
|
||||||
|
- Consider using typed constants for better type safety
|
||||||
|
|
||||||
|
## Code Style and Formatting
|
||||||
|
|
||||||
|
### Formatting
|
||||||
|
|
||||||
|
- Always use `gofmt` to format code
|
||||||
|
- Use `goimports` to manage imports automatically
|
||||||
|
- Keep line to 180 max at all times
|
||||||
|
- Add blank lines to separate logical groups of code
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
|
||||||
|
- Write comments in complete sentences
|
||||||
|
- Start sentences with the name of the thing being described
|
||||||
|
- Package comments should start with "Package [name]"
|
||||||
|
- Use line comments (`//`) for most comments
|
||||||
|
- Use block comments (`/* */`) sparingly, mainly for package documentation
|
||||||
|
- Document why, not what, unless the what is complex
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
- Check errors immediately after the function call
|
||||||
|
- Don't ignore errors using `_` unless you have a good reason (document why)
|
||||||
|
- Wrap errors with context using `fmt.Errorf` with `%w` verb
|
||||||
|
- Create custom error types when you need to check for specific errors
|
||||||
|
- Place error returns as the last return value
|
||||||
|
- Name error variables `err`
|
||||||
|
- Keep error messages lowercase and don't end with punctuation
|
||||||
|
|
||||||
|
### Logging
|
||||||
|
|
||||||
|
- Always use the codebase `log` package for logging
|
||||||
|
- Log errors at the point they occur using `log.Error(err)`
|
||||||
|
- Do not format the errors, let the `log` package handle it
|
||||||
|
- For complex function calls, use `defer log.Trace(time.Now(), args)`
|
||||||
|
where args are the function arguments at the start of the function.
|
||||||
|
|
||||||
|
### Control Flow
|
||||||
|
|
||||||
|
- **NEVER use `else` statements** - they create unnecessary nesting and reduce readability
|
||||||
|
- Use early returns to handle error cases and edge conditions first
|
||||||
|
- Use `continue` in loops to skip to the next iteration instead of nesting
|
||||||
|
- Use `break` to exit loops early instead of complex conditional logic
|
||||||
|
- Keep the main logic (happy path) left-aligned with minimal indentation
|
||||||
|
|
||||||
|
**❌ BAD - Don't do this:**
|
||||||
|
|
||||||
|
```go
|
||||||
|
func processEntry(entry *Entry) string {
|
||||||
|
if entry.Expired() {
|
||||||
|
return "expired"
|
||||||
|
} else {
|
||||||
|
if entry.TTL < 0 {
|
||||||
|
return "never expires"
|
||||||
|
} else {
|
||||||
|
return fmt.Sprintf("expires at %s", time.Unix(entry.Timestamp, 0))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**✅ GOOD - Do this instead:**
|
||||||
|
|
||||||
|
```go
|
||||||
|
func processEntry(entry *Entry) string {
|
||||||
|
if entry.Expired() {
|
||||||
|
return "expired"
|
||||||
|
}
|
||||||
|
|
||||||
|
if entry.TTL < 0 {
|
||||||
|
return "never expires"
|
||||||
|
}
|
||||||
|
|
||||||
|
return fmt.Sprintf("expires at %s", time.Unix(entry.Timestamp, 0))
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**❌ BAD - Nested loop logic:**
|
||||||
|
|
||||||
|
```go
|
||||||
|
for _, item := range items {
|
||||||
|
if item.IsValid() {
|
||||||
|
if item.ShouldProcess() {
|
||||||
|
// complex processing logic
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**✅ GOOD - Early continue:**
|
||||||
|
|
||||||
|
```go
|
||||||
|
for _, item := range items {
|
||||||
|
if !item.IsValid() {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
if !item.ShouldProcess() {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
// complex processing logic (happy path)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture and Project Structure
|
||||||
|
|
||||||
|
### Package Organization
|
||||||
|
|
||||||
|
- Follow standard Go project layout conventions
|
||||||
|
- Group related functionality into packages
|
||||||
|
- Avoid circular dependencies
|
||||||
|
|
||||||
|
### Dependency Management
|
||||||
|
|
||||||
|
- Use Go modules (`go.mod` and `go.sum`)
|
||||||
|
- Keep dependencies minimal
|
||||||
|
- Regularly update dependencies for security patches
|
||||||
|
- Use `go mod tidy` to clean up unused dependencies
|
||||||
|
- Vendor dependencies when necessary
|
||||||
|
|
||||||
|
## Type Safety and Language Features
|
||||||
|
|
||||||
|
### Type Definitions
|
||||||
|
|
||||||
|
- Define types to add meaning and type safety
|
||||||
|
- Use struct tags for JSON, YAML and TOML on exported fields
|
||||||
|
- Prefer explicit type conversions
|
||||||
|
- Use type assertions carefully and check the second return value
|
||||||
|
|
||||||
|
### Pointers vs Values
|
||||||
|
|
||||||
|
- Use pointers for large structs or when you need to modify the receiver
|
||||||
|
- Use values for small structs and when immutability is desired
|
||||||
|
- Be consistent within a type's method set
|
||||||
|
- Consider the zero value when choosing pointer vs value receivers
|
||||||
|
|
||||||
|
### Interfaces and Composition
|
||||||
|
|
||||||
|
- Accept interfaces, return concrete types
|
||||||
|
- Keep interfaces small (1-3 methods is ideal)
|
||||||
|
- Use embedding for composition
|
||||||
|
- Define interfaces close to where they're used, not where they're implemented
|
||||||
|
- Don't export interfaces unless necessary
|
||||||
|
|
||||||
|
## Concurrency
|
||||||
|
|
||||||
|
### Goroutines
|
||||||
|
|
||||||
|
- Don't create goroutines in libraries; let the caller control concurrency
|
||||||
|
- Always know how a goroutine will exit
|
||||||
|
- Use `sync.WaitGroup` or channels to wait for goroutines
|
||||||
|
- Avoid goroutine leaks by ensuring cleanup
|
||||||
|
|
||||||
|
### Channels
|
||||||
|
|
||||||
|
- Use channels to communicate between goroutines
|
||||||
|
- Don't communicate by sharing memory; share memory by communicating
|
||||||
|
- Close channels from the sender side, not the receiver
|
||||||
|
- Use buffered channels when you know the capacity
|
||||||
|
- Use `select` for non-blocking operations
|
||||||
|
|
||||||
|
### Synchronization
|
||||||
|
|
||||||
|
- Use `sync.Mutex` for protecting shared state
|
||||||
|
- Keep critical sections small
|
||||||
|
- Use `sync.RWMutex` when you have many readers
|
||||||
|
- Prefer channels over mutexes when possible
|
||||||
|
- Use `sync.Once` for one-time initialization
|
||||||
|
|
||||||
|
## Error Handling Patterns
|
||||||
|
|
||||||
|
### Creating Errors
|
||||||
|
|
||||||
|
- Use `errors.New` for simple static errors
|
||||||
|
- Use `fmt.Errorf` for errors with runtime values
|
||||||
|
- Create custom error types for domain-specific errors
|
||||||
|
- Export error variables for sentinel errors
|
||||||
|
- Use `errors.Is` and `errors.As` for error checking
|
||||||
|
|
||||||
|
### Error Propagation
|
||||||
|
|
||||||
|
- Add context when propagating errors up the stack
|
||||||
|
- Don't log and return errors (choose one)
|
||||||
|
- Handle errors at the appropriate level
|
||||||
|
- Consider using structured errors for better debugging
|
||||||
|
|
||||||
|
## Performance Optimization
|
||||||
|
|
||||||
|
### Memory Management
|
||||||
|
|
||||||
|
- Minimize allocations in hot paths
|
||||||
|
- Reuse objects when possible (consider `sync.Pool`)
|
||||||
|
- Use value receivers for small structs
|
||||||
|
- Preallocate slices when size is known
|
||||||
|
- Avoid unnecessary string conversions
|
||||||
|
|
||||||
|
### Profiling
|
||||||
|
|
||||||
|
- Use built-in profiling tools (`pprof`)
|
||||||
|
- Benchmark critical code paths
|
||||||
|
- Profile before making performance changes
|
||||||
|
- Focus on algorithmic improvements first
|
||||||
|
- Consider using `testing.B` for benchmarks
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Test Organization
|
||||||
|
|
||||||
|
- Keep tests in the same package (white-box testing)
|
||||||
|
- Use `_test` package suffix for black-box testing
|
||||||
|
- Name test files with `_test.go` suffix
|
||||||
|
- Place test files next to the code they test
|
||||||
|
|
||||||
|
### Writing Tests
|
||||||
|
|
||||||
|
- Name tests descriptively using `TestFunctionNameScenario`
|
||||||
|
- Use subtests with `t.Run` for better organization
|
||||||
|
- Test both success and error cases
|
||||||
|
- Use `testify/assert` and `testify/require` for assertions
|
||||||
|
- Include both positive and negative test cases
|
||||||
|
- Test edge cases and error conditions
|
||||||
|
- When including a standard library that conflicts with an existing import,
|
||||||
|
use the lib(library name) pattern to avoid conflicts.
|
||||||
|
Such as: `libtime` for the `time` package.
|
||||||
|
|
||||||
|
#### Table-driven tests are the default
|
||||||
|
|
||||||
|
One behavior under test = one test function with a table of cases. Never write several
|
||||||
|
near-identical test functions that differ only in input data, fixtures, or expected outcome —
|
||||||
|
those differences are table fields. A per-case fixture (a different map, config, or mock return)
|
||||||
|
is not a reason to split; put the fixture in the table. Shared setup (mocks, caches, `Init`
|
||||||
|
calls) runs once before the loop.
|
||||||
|
|
||||||
|
When adding cases to an existing test file, extend the existing table instead of adding a new
|
||||||
|
test function.
|
||||||
|
|
||||||
|
Only split into separate test functions when the flow genuinely differs: a different API under
|
||||||
|
test, or a setup/assertion sequence that cannot be expressed as table fields.
|
||||||
|
|
||||||
|
```go
|
||||||
|
// ✅ CORRECT: fixture and error expectation are table fields
|
||||||
|
cases := []struct {
|
||||||
|
Fixture Palette
|
||||||
|
Case string
|
||||||
|
Input Ansi
|
||||||
|
Expected Ansi
|
||||||
|
ExpectedError bool
|
||||||
|
}{
|
||||||
|
{Case: "literal", Fixture: Palette{"a": "#123456"}, Input: "p:a", Expected: "#123456"},
|
||||||
|
{Case: "invalid", Fixture: Palette{"a": "{{ broken"}, Input: "p:a", ExpectedError: true},
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ WRONG: TestResolveLiteral, TestResolveReference, TestResolveInvalid —
|
||||||
|
// three functions repeating the same setup with different data
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Helpers
|
||||||
|
|
||||||
|
- Mark helper functions with `t.Helper()`
|
||||||
|
- Create test fixtures for complex setup
|
||||||
|
- Use `testing.TB` interface for functions used in tests and benchmarks
|
||||||
|
- Clean up resources using `t.Cleanup()`
|
||||||
|
|
||||||
|
#### Global state: always save the original value and restore it
|
||||||
|
|
||||||
|
When a test mutates package-level variables (resolvers, loggers, clocks, `time.Local`, etc.),
|
||||||
|
save the original value into a local variable and restore it via `t.Cleanup`. Never restore to a
|
||||||
|
hardcoded value; you would overwrite whatever state preceded your test.
|
||||||
|
|
||||||
|
```go
|
||||||
|
// ✅ CORRECT: save original, restore original
|
||||||
|
origResolver := myPackageResolver
|
||||||
|
t.Cleanup(func() { myPackageResolver = origResolver })
|
||||||
|
myPackageResolver = fakeResolver
|
||||||
|
|
||||||
|
origLocal := time.Local
|
||||||
|
t.Cleanup(func() { time.Local = origLocal })
|
||||||
|
time.Local = time.UTC
|
||||||
|
|
||||||
|
// ❌ WRONG: restores to a hardcoded value instead of the pre-test value
|
||||||
|
defer func() { time.Local = time.FixedZone("UTC", 0) }()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security Best Practices
|
||||||
|
|
||||||
|
### Input Validation
|
||||||
|
|
||||||
|
- Validate all external input
|
||||||
|
- Use strong typing to prevent invalid states
|
||||||
|
- Sanitize data before using in SQL queries
|
||||||
|
- Be careful with file paths from user input
|
||||||
|
- Validate and escape data for different contexts (HTML, SQL, shell)
|
||||||
|
|
||||||
|
### Cryptography
|
||||||
|
|
||||||
|
- Use standard library crypto packages
|
||||||
|
- Never write your own cryptography
|
||||||
|
- Use crypto/rand for random number generation
|
||||||
|
- Store passwords using bcrypt or similar
|
||||||
|
- Use TLS for network communication
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
### Code Documentation
|
||||||
|
|
||||||
|
- Document all exported symbols
|
||||||
|
- Start documentation with the symbol name
|
||||||
|
- Use examples in documentation when helpful
|
||||||
|
- Keep documentation close to code
|
||||||
|
- Update documentation when code changes
|
||||||
|
|
||||||
|
### README and Documentation Files
|
||||||
|
|
||||||
|
- Include clear setup instructions
|
||||||
|
- Document dependencies and requirements
|
||||||
|
- Provide usage examples
|
||||||
|
- Document configuration options
|
||||||
|
- Include troubleshooting section
|
||||||
|
|
||||||
|
## Tools and Development Workflow
|
||||||
|
|
||||||
|
### Essential Tools
|
||||||
|
|
||||||
|
- `go fmt`: Format code
|
||||||
|
- `go vet`: Find suspicious constructs
|
||||||
|
- `golint` or `golangci-lint`: Additional linting
|
||||||
|
- `go test`: Run tests
|
||||||
|
- `go mod`: Manage dependencies
|
||||||
|
- `go generate`: Code generation
|
||||||
|
|
||||||
|
### Development Practices
|
||||||
|
|
||||||
|
- Run tests before committing
|
||||||
|
- Use pre-commit hooks for formatting and linting
|
||||||
|
- Keep commits focused and atomic
|
||||||
|
- Write clear, descriptive commit messages
|
||||||
|
- Review diffs before committing
|
||||||
|
|
||||||
|
### Pre-Commit Quality Gate
|
||||||
|
|
||||||
|
**REQUIRED BEFORE EVERY COMMIT.** Run the following commands in sequence after any Go code
|
||||||
|
change. Commit after all pass with zero errors. Never skip this step; these
|
||||||
|
linters catch real bugs and style violations that will be flagged in CI or code review.
|
||||||
|
|
||||||
|
1. **Code Modernization**: Apply modern Go best practices; this rewrites files in place
|
||||||
|
|
||||||
|
```bash
|
||||||
|
modernize --fix "./..."
|
||||||
|
```
|
||||||
|
|
||||||
|
> `modernize` modifies source files (e.g. replacing `strings.Split`
|
||||||
|
> with `strings.SplitSeq` for Go 1.24+ range loops). Always stage its changes and
|
||||||
|
> include them in the same commit as your feature code.
|
||||||
|
|
||||||
|
2. **Field Alignment**: Optimize struct field ordering for memory efficiency; this rewrites files in place
|
||||||
|
|
||||||
|
```bash
|
||||||
|
fieldalignment --fix "./..."
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Warning:** `fieldalignment` rewrites struct field order. Any inline struct
|
||||||
|
> literals that use **positional** (unnamed) field initialization (common in
|
||||||
|
> table-driven test files) will break after the reorder.
|
||||||
|
> **Always use named fields** in struct literals (e.g. `{Case: "foo", Now: t}`)
|
||||||
|
> so that the order of fields in the struct definition does not matter.
|
||||||
|
|
||||||
|
3. **Dependency Management**: Clean up and organize module dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
go mod tidy
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Formatting and Linting**: Ensure code follows standards (**must report zero errors**)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gofmt -w .
|
||||||
|
golangci-lint run
|
||||||
|
```
|
||||||
|
|
||||||
|
After steps 1 through 3, always run `git diff` to review auto-applied changes before staging them.
|
||||||
|
All four steps must complete with zero errors before the commit is created.
|
||||||
|
|
||||||
|
#### Platform-specific files (`_unix.go`, `_windows.go`, `_darwin.go`)
|
||||||
|
|
||||||
|
If you add or modify a file with a platform-specific suffix, also cross-compile to catch
|
||||||
|
issues the local OS linter skips. On Windows, run:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
$env:GOOS = "linux"; go build ./...; $env:GOOS = ""
|
||||||
|
```
|
||||||
|
|
||||||
|
On Linux/macOS, run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
GOOS=windows go build ./...
|
||||||
|
```
|
||||||
|
|
||||||
|
This catches import mismatches, missing symbols, and linter rules (like `modernize`
|
||||||
|
`strings.SplitSeq`) that apply on the non-host platform.
|
||||||
|
|
||||||
|
#### Common golangci-lint violations to fix before committing
|
||||||
|
|
||||||
|
These rules frequently fire on new code and are quick to resolve before linting:
|
||||||
|
|
||||||
|
| Linter | Trigger | Fix |
|
||||||
|
| ------ | ------- | --- |
|
||||||
|
| `goconst` | Same string literal occurs 3+ times | Extract to a named `const` |
|
||||||
|
| `gofmt` | Incorrect indentation or comment spacing | Run `gofmt -w .`; it fixes automatically |
|
||||||
|
| `dupl` | Two functions/test cases with near-identical structure | Add `//nolint:dupl` with a brief reason comment |
|
||||||
|
| `modernize` | `strings.Split` used in a `for range` (Go 1.24+) | Run `modernize --fix "./..."` (auto-fixes) |
|
||||||
|
|
||||||
|
## Common Pitfalls to Avoid
|
||||||
|
|
||||||
|
- Not checking errors
|
||||||
|
- Ignoring race conditions
|
||||||
|
- Creating goroutine leaks
|
||||||
|
- Not using defer for cleanup
|
||||||
|
- Modifying maps concurrently
|
||||||
|
- Confusing nil interfaces with nil pointers
|
||||||
|
- Forgetting to close resources (files, connections)
|
||||||
|
- Using global variables unnecessarily
|
||||||
|
- Over-using empty interfaces (`interface{}` or `any`)
|
||||||
|
- Not considering the zero value of types
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
---
|
||||||
|
name: markdown
|
||||||
|
description: >
|
||||||
|
Markdown formatting rules for this project. Apply when writing or editing
|
||||||
|
any .md or .mdx file, including documentation and website content.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Markdown Content Rules
|
||||||
|
|
||||||
|
The following markdown content rules are enforced in the validators:
|
||||||
|
|
||||||
|
1. Headings: Use appropriate heading levels (H2, H3, etc.) to structure your content.
|
||||||
|
Do not use an H1 heading, as this will be generated based on the title.
|
||||||
|
2. Lists: Use bullet points or numbered lists for lists. Ensure proper
|
||||||
|
indentation and spacing.
|
||||||
|
3. Code Blocks: Use fenced code blocks for code snippets. Specify the language
|
||||||
|
for syntax highlighting.
|
||||||
|
4. Links: Use proper markdown syntax for links. Ensure that links are valid and
|
||||||
|
accessible.
|
||||||
|
5. Images: Use proper markdown syntax for images. Include alt text for
|
||||||
|
accessibility.
|
||||||
|
6. Tables: Use markdown tables for tabular data. Ensure proper formatting and
|
||||||
|
alignment.
|
||||||
|
7. Line Length: Limit line length to 120 characters for readability.
|
||||||
|
8. Whitespace: Use appropriate whitespace to separate sections and improve readability.
|
||||||
|
9. Front Matter: Include YAML front matter at the beginning of the file with required metadata fields.
|
||||||
|
|
||||||
|
## Formatting and Structure
|
||||||
|
|
||||||
|
Follow these guidelines for formatting and structuring your markdown content:
|
||||||
|
|
||||||
|
- Headings: Use `##` for H2 and `###` for H3. Ensure that headings are used in a
|
||||||
|
hierarchical manner. Recommend restructuring if content includes H4, and more
|
||||||
|
strongly recommend for H5.
|
||||||
|
- Lists: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with two spaces.
|
||||||
|
- Code Blocks: Use fenced code blocks with a language for syntax highlighting:
|
||||||
|
|
||||||
|
```go
|
||||||
|
fmt.Println("hello")
|
||||||
|
```
|
||||||
|
|
||||||
|
- Links:
|
||||||
|
- Inline: `[Docs](https://example.com/docs)`
|
||||||
|
- Reference-style: `[Docs][docs]` and add at the end of the page:
|
||||||
|
`[docs]: https://example.com/docs`
|
||||||
|
- Images: Use `` for images. Include a brief description
|
||||||
|
of the image in the alt text.
|
||||||
|
- Tables: Use `|` to create tables. Ensure that columns are properly aligned
|
||||||
|
and headers are included.
|
||||||
|
- Line Length: Break lines at 120 characters to improve readability. Use soft
|
||||||
|
line breaks for long paragraphs.
|
||||||
|
- Whitespace: Use blank lines to separate sections and improve readability. Avoid excessive whitespace.
|
||||||
|
|
||||||
|
## Post-Edit Verification
|
||||||
|
|
||||||
|
After editing any `.md` or `.mdx` file, run the following command and resolve all reported
|
||||||
|
errors before considering the task complete:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
npx markdownlint-cli2 <edited-file>
|
||||||
|
```
|
||||||
|
|
||||||
|
This closes the feedback loop so violations are caught and fixed immediately rather than
|
||||||
|
relying on an external CI run.
|
||||||
|
|
||||||
|
## Validation Requirements
|
||||||
|
|
||||||
|
Ensure compliance with the following validation requirements:
|
||||||
|
|
||||||
|
- Content Rules: Ensure that the content follows the markdown content rules
|
||||||
|
specified above.
|
||||||
|
- Formatting: Ensure that the content is properly formatted and structured
|
||||||
|
according to the guidelines.
|
||||||
|
- Validation: Run the validation tools to check for compliance with the rules
|
||||||
|
and guidelines.
|
||||||
@@ -0,0 +1,334 @@
|
|||||||
|
---
|
||||||
|
name: powershell
|
||||||
|
description: >
|
||||||
|
PowerShell cmdlet conventions for this project. Apply when writing or
|
||||||
|
reviewing any .ps1 or module file.
|
||||||
|
---
|
||||||
|
|
||||||
|
# PowerShell Cmdlet Development Guidelines
|
||||||
|
|
||||||
|
## Naming Conventions
|
||||||
|
|
||||||
|
- **Verb-Noun Format:**
|
||||||
|
- Use approved PowerShell verbs (Get-Verb)
|
||||||
|
- Use singular nouns
|
||||||
|
- PascalCase for both verb and noun
|
||||||
|
- Avoid special characters and spaces
|
||||||
|
|
||||||
|
- **Parameter Names:**
|
||||||
|
- Use PascalCase
|
||||||
|
- Choose clear, descriptive names
|
||||||
|
- Use singular form unless always multiple
|
||||||
|
- Follow PowerShell standard names
|
||||||
|
|
||||||
|
- **Variable Names:**
|
||||||
|
- Use PascalCase for public variables
|
||||||
|
- Use camelCase for private variables
|
||||||
|
- Avoid abbreviations
|
||||||
|
- Use descriptive names
|
||||||
|
|
||||||
|
- **Alias Avoidance:**
|
||||||
|
- Use full cmdlet names
|
||||||
|
- Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci)
|
||||||
|
- Document any custom aliases
|
||||||
|
- Use full parameter names
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
function Get-UserProfile {
|
||||||
|
[CmdletBinding()]
|
||||||
|
param(
|
||||||
|
[Parameter(Mandatory)]
|
||||||
|
[string]$Username,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[ValidateSet('Basic', 'Detailed')]
|
||||||
|
[string]$ProfileType = 'Basic'
|
||||||
|
)
|
||||||
|
|
||||||
|
process {
|
||||||
|
# Logic here
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parameter Design
|
||||||
|
|
||||||
|
- **Standard Parameters:**
|
||||||
|
- Use common parameter names (`Path`, `Name`, `Force`)
|
||||||
|
- Follow built-in cmdlet conventions
|
||||||
|
- Use aliases for specialized terms
|
||||||
|
- Document parameter purpose
|
||||||
|
|
||||||
|
- **Parameter Names:**
|
||||||
|
- Use singular form unless always multiple
|
||||||
|
- Choose clear, descriptive names
|
||||||
|
- Follow PowerShell conventions
|
||||||
|
- Use PascalCase formatting
|
||||||
|
|
||||||
|
- **Type Selection:**
|
||||||
|
- Use common .NET types
|
||||||
|
- Implement proper validation
|
||||||
|
- Consider ValidateSet for limited options
|
||||||
|
- Enable tab completion where possible
|
||||||
|
|
||||||
|
- **Switch Parameters:**
|
||||||
|
- Use [switch] for boolean flags
|
||||||
|
- Avoid $true/$false parameters
|
||||||
|
- Default to $false when omitted
|
||||||
|
- Use clear action names
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
function Set-ResourceConfiguration {
|
||||||
|
[CmdletBinding()]
|
||||||
|
param(
|
||||||
|
[Parameter(Mandatory)]
|
||||||
|
[string]$Name,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[ValidateSet('Dev', 'Test', 'Prod')]
|
||||||
|
[string]$Environment = 'Dev',
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[switch]$Force,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[ValidateNotNullOrEmpty()]
|
||||||
|
[string[]]$Tags
|
||||||
|
)
|
||||||
|
|
||||||
|
process {
|
||||||
|
# Logic here
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pipeline and Output
|
||||||
|
|
||||||
|
- **Pipeline Input:**
|
||||||
|
- Use `ValueFromPipeline` for direct object input
|
||||||
|
- Use `ValueFromPipelineByPropertyName` for property mapping
|
||||||
|
- Implement Begin/Process/End blocks for pipeline handling
|
||||||
|
- Document pipeline input requirements
|
||||||
|
|
||||||
|
- **Output Objects:**
|
||||||
|
- Return rich objects, not formatted text
|
||||||
|
- Use PSCustomObject for structured data
|
||||||
|
- Avoid Write-Host for data output
|
||||||
|
- Enable downstream cmdlet processing
|
||||||
|
|
||||||
|
- **Pipeline Streaming:**
|
||||||
|
- Output one object at a time
|
||||||
|
- Use process block for streaming
|
||||||
|
- Avoid collecting large arrays
|
||||||
|
- Enable immediate processing
|
||||||
|
|
||||||
|
- **PassThru Pattern:**
|
||||||
|
- Default to no output for action cmdlets
|
||||||
|
- Implement `-PassThru` switch for object return
|
||||||
|
- Return modified/created object with `-PassThru`
|
||||||
|
- Use verbose/warning for status updates
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
function Update-ResourceStatus {
|
||||||
|
[CmdletBinding()]
|
||||||
|
param(
|
||||||
|
[Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
|
||||||
|
[string]$Name,
|
||||||
|
|
||||||
|
[Parameter(Mandatory)]
|
||||||
|
[ValidateSet('Active', 'Inactive', 'Maintenance')]
|
||||||
|
[string]$Status,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[switch]$PassThru
|
||||||
|
)
|
||||||
|
|
||||||
|
begin {
|
||||||
|
Write-Verbose "Starting resource status update process"
|
||||||
|
$timestamp = Get-Date
|
||||||
|
}
|
||||||
|
|
||||||
|
process {
|
||||||
|
# Process each resource individually
|
||||||
|
Write-Verbose "Processing resource: $Name"
|
||||||
|
|
||||||
|
$resource = [PSCustomObject]@{
|
||||||
|
Name = $Name
|
||||||
|
Status = $Status
|
||||||
|
LastUpdated = $timestamp
|
||||||
|
UpdatedBy = $env:USERNAME
|
||||||
|
}
|
||||||
|
|
||||||
|
# Only output if PassThru is specified
|
||||||
|
if ($PassThru) {
|
||||||
|
Write-Output $resource
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
end {
|
||||||
|
Write-Verbose "Resource status update process completed"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling and Safety
|
||||||
|
|
||||||
|
- **ShouldProcess Implementation:**
|
||||||
|
- Use `[CmdletBinding(SupportsShouldProcess = $true)]`
|
||||||
|
- Set appropriate `ConfirmImpact` level
|
||||||
|
- Call `$PSCmdlet.ShouldProcess()` for system changes
|
||||||
|
- Use `ShouldContinue()` for additional confirmations
|
||||||
|
|
||||||
|
- **Message Streams:**
|
||||||
|
- `Write-Verbose` for operational details with `-Verbose`
|
||||||
|
- `Write-Warning` for warning conditions
|
||||||
|
- `Write-Error` for recoverable errors that allow execution to continue
|
||||||
|
- `throw` for fatal errors that stop execution
|
||||||
|
- Avoid `Write-Host` except for user interface text
|
||||||
|
|
||||||
|
- **Error Handling Pattern:**
|
||||||
|
- Use try/catch blocks for error management
|
||||||
|
- Set appropriate ErrorAction preferences
|
||||||
|
- Return clear, specific error messages
|
||||||
|
- Use ErrorVariable when needed
|
||||||
|
- Include proper fatal vs recoverable error handling
|
||||||
|
|
||||||
|
- **Non-Interactive Design:**
|
||||||
|
- Accept input via parameters
|
||||||
|
- Avoid `Read-Host` in scripts
|
||||||
|
- Support automation scenarios
|
||||||
|
- Document all required inputs
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
function Remove-UserAccount {
|
||||||
|
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
|
||||||
|
param(
|
||||||
|
[Parameter(Mandatory, ValueFromPipeline)]
|
||||||
|
[ValidateNotNullOrEmpty()]
|
||||||
|
[string]$Username,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[switch]$Force
|
||||||
|
)
|
||||||
|
|
||||||
|
begin {
|
||||||
|
Write-Verbose "Starting user account removal process"
|
||||||
|
$ErrorActionPreference = 'Stop'
|
||||||
|
}
|
||||||
|
|
||||||
|
process {
|
||||||
|
try {
|
||||||
|
# Validation
|
||||||
|
if (-not (Test-UserExists -Username $Username)) {
|
||||||
|
Write-Error "User account '$Username' not found"
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
# Confirmation
|
||||||
|
$shouldProcessMessage = "Remove user account '$Username'"
|
||||||
|
if ($Force -or $PSCmdlet.ShouldProcess($Username, $shouldProcessMessage)) {
|
||||||
|
Write-Verbose "Removing user account: $Username"
|
||||||
|
|
||||||
|
# Main operation
|
||||||
|
Remove-ADUser -Identity $Username -ErrorAction Stop
|
||||||
|
Write-Warning "User account '$Username' has been removed"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
catch [Microsoft.ActiveDirectory.Management.ADException] {
|
||||||
|
Write-Error "Active Directory error: $_"
|
||||||
|
throw
|
||||||
|
}
|
||||||
|
catch {
|
||||||
|
Write-Error "Unexpected error removing user account: $_"
|
||||||
|
throw
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
end {
|
||||||
|
Write-Verbose "User account removal process completed"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation and Style
|
||||||
|
|
||||||
|
- **Comment-Based Docs:** Include comment-based documentation for any public-facing function or cmdlet. Inside the function,
|
||||||
|
add a `<# ... #>` block with at least:
|
||||||
|
- `.SYNOPSIS` Brief description
|
||||||
|
- `.DESCRIPTION` Detailed explanation
|
||||||
|
- `.EXAMPLE` sections with practical usage
|
||||||
|
- `.PARAMETER` descriptions
|
||||||
|
- `.OUTPUTS` Type of output returned
|
||||||
|
- `.NOTES` Additional information
|
||||||
|
|
||||||
|
- **Consistent Formatting:**
|
||||||
|
- Follow consistent PowerShell style
|
||||||
|
- Use proper indentation (4 spaces recommended)
|
||||||
|
- Opening braces on same line as statement
|
||||||
|
- Closing braces on new line
|
||||||
|
- Use line breaks after pipeline operators
|
||||||
|
- PascalCase for function and parameter names
|
||||||
|
- Avoid unnecessary whitespace
|
||||||
|
|
||||||
|
- **Pipeline Support:**
|
||||||
|
- Implement Begin/Process/End blocks for pipeline functions
|
||||||
|
- Use ValueFromPipeline where appropriate
|
||||||
|
- Support pipeline input by property name
|
||||||
|
- Return proper objects, not formatted text
|
||||||
|
|
||||||
|
- **Avoid Aliases:** Use full cmdlet names and parameters
|
||||||
|
- Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci)
|
||||||
|
- Use `Where-Object` instead of `?` or `where`
|
||||||
|
- Use `ForEach-Object` instead of `%`
|
||||||
|
- Use `Get-ChildItem` instead of `ls` or `dir`
|
||||||
|
|
||||||
|
## Full Example: End-to-End Cmdlet Pattern
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
function New-Resource {
|
||||||
|
[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
|
||||||
|
param(
|
||||||
|
[Parameter(Mandatory = $true,
|
||||||
|
ValueFromPipeline = $true,
|
||||||
|
ValueFromPipelineByPropertyName = $true)]
|
||||||
|
[ValidateNotNullOrEmpty()]
|
||||||
|
[string]$Name,
|
||||||
|
|
||||||
|
[Parameter()]
|
||||||
|
[ValidateSet('Development', 'Production')]
|
||||||
|
[string]$Environment = 'Development'
|
||||||
|
)
|
||||||
|
|
||||||
|
begin {
|
||||||
|
Write-Verbose "Starting resource creation process"
|
||||||
|
}
|
||||||
|
|
||||||
|
process {
|
||||||
|
try {
|
||||||
|
if ($PSCmdlet.ShouldProcess($Name, "Create new resource")) {
|
||||||
|
# Resource creation logic here
|
||||||
|
Write-Output ([PSCustomObject]@{
|
||||||
|
Name = $Name
|
||||||
|
Environment = $Environment
|
||||||
|
Created = Get-Date
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
catch {
|
||||||
|
Write-Error "Failed to create resource: $_"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
end {
|
||||||
|
Write-Verbose "Completed resource creation process"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,157 @@
|
|||||||
|
# Writing Clearly and Concisely
|
||||||
|
|
||||||
|
A skill that applies William Strunk Jr.'s timeless writing principles to produce clearer, stronger, more professional prose while avoiding common AI writing patterns.
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This skill helps you write better prose for human readers. It draws from two sources:
|
||||||
|
|
||||||
|
1. **The Elements of Style** (Strunk, 1918) - Time-tested rules for clear, forceful writing
|
||||||
|
2. **AI Pattern Avoidance** - Research-backed guidance on avoiding generic, puffy language that LLMs tend to produce
|
||||||
|
|
||||||
|
Whether you're writing documentation, commit messages, error messages, or any text humans will read, this skill helps you cut fluff and say what you mean.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
Use this skill whenever you write prose for humans:
|
||||||
|
|
||||||
|
- **Documentation** - README files, API docs, technical explanations
|
||||||
|
- **Git workflow** - Commit messages, pull request descriptions
|
||||||
|
- **User-facing text** - Error messages, UI copy, help text, tooltips
|
||||||
|
- **Code comments** - Inline documentation, docstrings
|
||||||
|
- **Reports and summaries** - Status updates, analysis, explanations
|
||||||
|
- **Editing** - Improving clarity of existing text
|
||||||
|
|
||||||
|
**Trigger phrases:**
|
||||||
|
- "Write documentation for..."
|
||||||
|
- "Draft a README"
|
||||||
|
- "Edit this for clarity"
|
||||||
|
- "Make this more concise"
|
||||||
|
- "Review this commit message"
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
1. **Load the skill** when writing prose for human readers
|
||||||
|
2. **Apply Strunk's core principles** - active voice, positive form, concrete language, cut needless words
|
||||||
|
3. **Avoid AI patterns** - no puffery, no empty phrases, no promotional adjectives
|
||||||
|
4. **Reference detailed guides** when needed for specific rules
|
||||||
|
|
||||||
|
### Context-Efficient Approach
|
||||||
|
|
||||||
|
The skill uses progressive disclosure to save context:
|
||||||
|
|
||||||
|
- **SKILL.md** (~1,000 tokens) loads first with the core rules
|
||||||
|
- **Reference files** (1,000-4,500 tokens each) load only when needed
|
||||||
|
- **Most tasks need only one file**: `03-elementary-principles-of-composition.md`
|
||||||
|
|
||||||
|
For tight context situations, dispatch a subagent with your draft and the relevant section file.
|
||||||
|
|
||||||
|
## Key Features
|
||||||
|
|
||||||
|
### Strunk's Core Rules
|
||||||
|
|
||||||
|
The skill emphasizes these principles from *The Elements of Style*:
|
||||||
|
|
||||||
|
| Rule | Principle |
|
||||||
|
|------|-----------|
|
||||||
|
| 10 | Use active voice |
|
||||||
|
| 11 | Put statements in positive form |
|
||||||
|
| 12 | Use definite, specific, concrete language |
|
||||||
|
| 13 | Omit needless words |
|
||||||
|
| 16 | Keep related words together |
|
||||||
|
| 18 | Place emphatic words at end of sentence |
|
||||||
|
|
||||||
|
### AI Pattern Detection
|
||||||
|
|
||||||
|
The skill identifies and eliminates common LLM writing patterns:
|
||||||
|
|
||||||
|
- **Puffery**: pivotal, crucial, vital, testament, enduring legacy
|
||||||
|
- **Empty "-ing" phrases**: ensuring reliability, showcasing features
|
||||||
|
- **Promotional adjectives**: groundbreaking, seamless, robust, cutting-edge
|
||||||
|
- **Overused AI vocabulary**: delve, leverage, multifaceted, foster, realm, tapestry
|
||||||
|
- **Formatting overuse**: excessive bullets, emoji decorations, bold on every other word
|
||||||
|
|
||||||
|
## Reference Files
|
||||||
|
|
||||||
|
| Section | File | Tokens | Content |
|
||||||
|
|---------|------|--------|---------|
|
||||||
|
| Grammar & punctuation | `02-elementary-rules-of-usage.md` | ~2,500 | Comma rules, possessives, sentence structure |
|
||||||
|
| Composition principles | `03-elementary-principles-of-composition.md` | ~4,500 | Active voice, concision, paragraph structure |
|
||||||
|
| Formatting | `04-a-few-matters-of-form.md` | ~1,000 | Headings, quotations, formatting conventions |
|
||||||
|
| Word choice | `05-words-and-expressions-commonly-misused.md` | ~4,000 | Common errors, word selection |
|
||||||
|
| AI patterns | `signs-of-ai-writing.md` | ~25,000 | Wikipedia editors' field guide to AI detection |
|
||||||
|
|
||||||
|
## Usage Examples
|
||||||
|
|
||||||
|
### Example 1: Tightening a Commit Message
|
||||||
|
|
||||||
|
**Before:**
|
||||||
|
> This commit implements the functionality for ensuring that user authentication is properly handled, showcasing robust error handling capabilities.
|
||||||
|
|
||||||
|
**After:**
|
||||||
|
> Add user authentication with error handling
|
||||||
|
|
||||||
|
### Example 2: Rewriting Documentation
|
||||||
|
|
||||||
|
**Before:**
|
||||||
|
> This groundbreaking feature leverages cutting-edge technology to deliver a seamless experience, fostering better engagement and driving impactful results.
|
||||||
|
|
||||||
|
**After:**
|
||||||
|
> This feature uses WebSocket connections to update the dashboard in real time.
|
||||||
|
|
||||||
|
### Example 3: Fixing Passive Voice
|
||||||
|
|
||||||
|
**Before:**
|
||||||
|
> The configuration file is read by the application at startup.
|
||||||
|
|
||||||
|
**After:**
|
||||||
|
> The application reads the configuration file at startup.
|
||||||
|
|
||||||
|
### Example 4: Removing Hedging
|
||||||
|
|
||||||
|
**Before:**
|
||||||
|
> It is important to note that the API might potentially return an error in certain situations.
|
||||||
|
|
||||||
|
**After:**
|
||||||
|
> The API returns an error when the token expires.
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Be specific, not grandiose** - Say what it actually does, not how important it is
|
||||||
|
2. **Cut first, add later** - Remove words until meaning suffers, then add back what's needed
|
||||||
|
3. **Prefer active voice** - "The function returns X" beats "X is returned by the function"
|
||||||
|
4. **State positively** - "He forgot" beats "He did not remember"
|
||||||
|
5. **Use concrete language** - "The server crashed" beats "An issue occurred"
|
||||||
|
6. **Load reference files sparingly** - Most tasks need only `03-elementary-principles-of-composition.md`
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
writing-clearly-and-concisely/
|
||||||
|
SKILL.md # Main skill definition
|
||||||
|
README.md # This file
|
||||||
|
signs-of-ai-writing.md # AI pattern detection guide
|
||||||
|
elements-of-style/
|
||||||
|
01-introductory.md
|
||||||
|
02-elementary-rules-of-usage.md
|
||||||
|
03-elementary-principles-of-composition.md
|
||||||
|
04-a-few-matters-of-form.md
|
||||||
|
05-words-and-expressions-commonly-misused.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
**Claude Code:**
|
||||||
|
```bash
|
||||||
|
cp -r skills/writing-clearly-and-concisely ~/.claude/skills/
|
||||||
|
```
|
||||||
|
|
||||||
|
**Claude.ai:**
|
||||||
|
Add the skill to project knowledge or paste SKILL.md contents into your conversation.
|
||||||
|
|
||||||
|
## Attribution
|
||||||
|
|
||||||
|
- Original skill by @joshuadavidthomas from [joshuadavidthomas/agent-skills](https://github.com/joshuadavidthomas/agent-skills) (MIT)
|
||||||
|
- Adapted from [obra/the-elements-of-style](https://github.com/obra/the-elements-of-style)
|
||||||
|
- Writing principles from *The Elements of Style* by William Strunk Jr. (1918)
|
||||||
|
- AI pattern research from Wikipedia's field guide to AI-generated content detection
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
---
|
||||||
|
name: writing-clearly-and-concisely
|
||||||
|
description: Apply whenever writing content a human will read — emails, documents, reports, documentation, messages, UI copy, commit messages, explanations, or any other prose. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Writing Clearly and Concisely
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Write with clarity and force. This skill covers what to do (Strunk) and what not to do (AI patterns).
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
Use this skill whenever you write content a human will read:
|
||||||
|
|
||||||
|
- Emails, messages, and any direct communication
|
||||||
|
- Documents, reports, summaries, proposals
|
||||||
|
- Documentation, README files, technical explanations
|
||||||
|
- Commit messages, pull request descriptions
|
||||||
|
- Error messages, UI copy, help text, comments
|
||||||
|
- Any other prose meant for human eyes
|
||||||
|
|
||||||
|
**If a human will read it, this skill applies — no exceptions.**
|
||||||
|
|
||||||
|
## Limited Context Strategy
|
||||||
|
|
||||||
|
When context is tight:
|
||||||
|
|
||||||
|
1. Write your draft using judgment
|
||||||
|
2. Dispatch a subagent with your draft and the relevant section file
|
||||||
|
3. Have the subagent copyedit and return the revision
|
||||||
|
|
||||||
|
Loading a single section (~1,000-4,500 tokens) instead of everything saves significant context.
|
||||||
|
|
||||||
|
## Elements of Style
|
||||||
|
|
||||||
|
William Strunk Jr.'s *The Elements of Style* (1918) teaches you to write clearly and cut ruthlessly.
|
||||||
|
|
||||||
|
### Rules
|
||||||
|
|
||||||
|
**Elementary Rules of Usage (Grammar/Punctuation)**:
|
||||||
|
|
||||||
|
1. Form possessive singular by adding 's
|
||||||
|
2. Use comma after each term in series except last
|
||||||
|
3. Enclose parenthetic expressions between commas
|
||||||
|
4. Comma before conjunction introducing co-ordinate clause
|
||||||
|
5. Don't join independent clauses by comma
|
||||||
|
6. Don't break sentences in two
|
||||||
|
7. Participial phrase at beginning refers to grammatical subject
|
||||||
|
|
||||||
|
**Elementary Principles of Composition**:
|
||||||
|
|
||||||
|
8. One paragraph per topic
|
||||||
|
9. Begin paragraph with topic sentence
|
||||||
|
10. **Use active voice**
|
||||||
|
11. **Put statements in positive form**
|
||||||
|
12. **Use definite, specific, concrete language**
|
||||||
|
13. **Omit needless words**
|
||||||
|
14. Avoid succession of loose sentences
|
||||||
|
15. Express co-ordinate ideas in similar form
|
||||||
|
16. **Keep related words together**
|
||||||
|
17. Keep to one tense in summaries
|
||||||
|
18. **Place emphatic words at end of sentence**
|
||||||
|
|
||||||
|
### Reference Files
|
||||||
|
|
||||||
|
The rules above are summarized from Strunk's original text. For complete explanations with examples:
|
||||||
|
|
||||||
|
| Section | File | ~Tokens |
|
||||||
|
|---------|------|---------|
|
||||||
|
| Grammar, punctuation, comma rules | `02-elementary-rules-of-usage.md` | 2,500 |
|
||||||
|
| Paragraph structure, active voice, concision | `03-elementary-principles-of-composition.md` | 4,500 |
|
||||||
|
| Headings, quotations, formatting | `04-a-few-matters-of-form.md` | 1,000 |
|
||||||
|
| Word choice, common errors | `05-words-and-expressions-commonly-misused.md` | 4,000 |
|
||||||
|
|
||||||
|
**Most tasks need only `03-elementary-principles-of-composition.md`** — it covers active voice, positive form, concrete language, and omitting needless words.
|
||||||
|
|
||||||
|
## AI Writing Patterns to Avoid
|
||||||
|
|
||||||
|
LLMs regress to statistical means, producing generic, puffy prose. Avoid:
|
||||||
|
|
||||||
|
- **Puffery:** pivotal, crucial, vital, testament, enduring legacy
|
||||||
|
- **Empty "-ing" phrases:** ensuring reliability, showcasing features, highlighting capabilities
|
||||||
|
- **Promotional adjectives:** groundbreaking, seamless, robust, cutting-edge
|
||||||
|
- **Overused AI vocabulary:** delve, leverage, multifaceted, foster, realm, tapestry
|
||||||
|
- **Em dashes:** never use em dashes (— or --); restructure the sentence instead
|
||||||
|
- **Formatting overuse:** excessive bullets, emoji decorations, bold on every other word
|
||||||
|
|
||||||
|
Be specific, not grandiose. Say what it actually does.
|
||||||
|
|
||||||
|
For comprehensive research on why these patterns occur, see `signs-of-ai-writing.md`. Wikipedia editors developed this guide to detect AI-generated submissions — their patterns are well-documented and field-tested.
|
||||||
|
|
||||||
|
## Bottom Line
|
||||||
|
|
||||||
|
Writing for humans? Load the relevant section from `elements-of-style/` and apply the rules. For most tasks, `03-elementary-principles-of-composition.md` covers what matters most.
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
## I. Introductory
|
||||||
|
|
||||||
|
This handbook summarizes the essentials of plain English style. It focuses on the rules of usage and principles of composition most often broken, offering a compact alternative to exhaustive manuals. Master the guidance here, then look to the best authors for finer points of style.
|
||||||
+214
@@ -0,0 +1,214 @@
|
|||||||
|
## II. Elementary Rules Of Usage
|
||||||
|
|
||||||
|
### Rule 1. Form the possessive singular of nouns by adding 's.
|
||||||
|
|
||||||
|
Follow this rule whatever the final consonant. Thus write,
|
||||||
|
|
||||||
|
Charles's friend
|
||||||
|
|
||||||
|
Burns's poems
|
||||||
|
|
||||||
|
the witch's malice
|
||||||
|
|
||||||
|
This is the usage of the United States Government Printing Office and of the Oxford University Press.
|
||||||
|
|
||||||
|
Exceptions are the possessive of ancient proper names ending in *-es* and *-is*, the possessive *Jesus'*, and such forms as *for conscience' sake*, *for righteousness' sake*. But such forms as *Achilles' heel*, *Moses' laws*, *Isis' temple* are commonly replaced by
|
||||||
|
|
||||||
|
the heel of Achilles
|
||||||
|
|
||||||
|
the laws of Moses
|
||||||
|
|
||||||
|
the temple of Isis
|
||||||
|
|
||||||
|
The pronominal possessives *hers*, *its*, *theirs*, *yours*, and *oneself* have no apostrophe.
|
||||||
|
|
||||||
|
### Rule 2. In a series of three or more terms with a single conjunction, use a comma after each term except the last.
|
||||||
|
|
||||||
|
Thus write,
|
||||||
|
|
||||||
|
red, white, and blue
|
||||||
|
|
||||||
|
gold, silver, or copper
|
||||||
|
|
||||||
|
He opened the letter, read it, and made a note of its contents.
|
||||||
|
|
||||||
|
This is also the usage of the Government Printing Office and of the Oxford University Press.
|
||||||
|
|
||||||
|
In the names of business firms the last comma is omitted, as,
|
||||||
|
|
||||||
|
Brown, Shipley & Co.
|
||||||
|
|
||||||
|
### Rule 3. Enclose parenthetic expressions between commas.
|
||||||
|
|
||||||
|
The best way to see a country, unless you are pressed for time, is to travel on foot.
|
||||||
|
|
||||||
|
This rule is difficult to apply; it is frequently hard to decide whether a single word, such as *however*, or a brief phrase, is or is not parenthetic. If the interruption to the flow of the sentence is but slight, the writer may safely omit the commas. But whether the interruption be slight or considerable, he must never insert one comma and omit the other. Such punctuation as
|
||||||
|
|
||||||
|
Marjorie's husband, Colonel Nelson paid us a visit yesterday,
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
My brother you will be pleased to hear, is now in perfect health,
|
||||||
|
|
||||||
|
is indefensible.
|
||||||
|
|
||||||
|
If a parenthetic expression is preceded by a conjunction, place the first comma before the conjunction, not after it.
|
||||||
|
|
||||||
|
He saw us coming, and unaware that we had learned of his treachery, greeted us with a smile.
|
||||||
|
|
||||||
|
Always to be regarded as parenthetic and to be enclosed between commas (or, at the end of the sentence, between comma and period) are the following:
|
||||||
|
|
||||||
|
\(1\) the year, when forming part of a date, and the day of the month, when following the day of the week:
|
||||||
|
|
||||||
|
February to July, 1916.
|
||||||
|
|
||||||
|
April 6, 1917.
|
||||||
|
|
||||||
|
Monday, November 11, 1918.
|
||||||
|
|
||||||
|
\(2\) the abbreviations *etc.* and *jr.*
|
||||||
|
|
||||||
|
\(3\) non-restrictive relative clauses, that is, those which do not serve to identify or define the antecedent noun, and similar clauses introduced by conjunctions indicating time or place.
|
||||||
|
|
||||||
|
The audience, which had at first been indifferent, became more and more interested.
|
||||||
|
|
||||||
|
In this sentence the clause introduced by *which* does not serve to tell which of several possible audiences is meant; what audience is in question is supposed to be already known. The clause adds, parenthetically, a statement supplementing that in the main clause. The sentence is virtually a combination of two statements which might have been made independently:
|
||||||
|
|
||||||
|
The audience had at first been indifferent. It became more and more interested.
|
||||||
|
|
||||||
|
Compare the restrictive relative clause, not set off by commas, in the sentence,
|
||||||
|
|
||||||
|
The candidate who best meets these requirements will obtain the place.
|
||||||
|
|
||||||
|
Here the clause introduced by *who* does serve to tell which of several possible candidates is meant; the sentence cannot be split up into two independent statements.
|
||||||
|
|
||||||
|
The difference in punctuation in the two sentences following is based on the same principle:
|
||||||
|
|
||||||
|
Nether Stowey, where Coleridge wrote The Rime of the Ancient Mariner, is a few miles from Bridgewater.
|
||||||
|
|
||||||
|
The day will come when you will admit your mistake.
|
||||||
|
|
||||||
|
Nether Stowey is completely identified by its name; the statement about Coleridge is therefore supplementary and parenthetic. The *day* spoken of is identified only by the dependent clause, which is therefore restrictive.
|
||||||
|
|
||||||
|
Similar in principle to the enclosing of parenthetic expressions between commas is the setting off by commas of phrases or dependent clauses preceding or following the main clause of a sentence.
|
||||||
|
|
||||||
|
Partly by hard fighting, partly by diplomatic skill, they enlarged their dominions to the east, and rose to royal rank with the possession of Sicily, exchanged afterwards for Sardinia.
|
||||||
|
|
||||||
|
Other illustrations may be found in sentences quoted under Rules 4, 5, 6, 7, 16, and 18.
|
||||||
|
|
||||||
|
The writer should be careful not to set off independent clauses by commas: see under Rule 5.
|
||||||
|
|
||||||
|
### Rule 4. Place a comma before a conjunction introducing a co-ordinate clause.
|
||||||
|
|
||||||
|
The early records of the city have disappeared, and the story of its first years can no longer be reconstructed.
|
||||||
|
|
||||||
|
The situation is perilous, but there is still one chance of escape.
|
||||||
|
|
||||||
|
Sentences of this type, isolated from their context, may seem to be in need of rewriting. As they make complete sense when the comma is reached, the second clause has the appearance of an afterthought. Further, *and* is the least specific of connectives. Used between independent clauses, it indicates only that a relation exists between them without defining that relation. In the example above, the relation is that of cause and result. The two sentences might be rewritten:
|
||||||
|
|
||||||
|
As the early records of the city have disappeared, the story of its first years can no longer be reconstructed.
|
||||||
|
|
||||||
|
Although the situation is perilous, there is still one chance of escape.
|
||||||
|
|
||||||
|
Or the subordinate clauses might be replaced by phrases:
|
||||||
|
|
||||||
|
Owing to the disappearance of the early records of the city, the story of its first years can no longer be reconstructed.
|
||||||
|
|
||||||
|
In this perilous situation, there is still one chance of escape.
|
||||||
|
|
||||||
|
But a writer may err by making his sentences too uniformly compact and periodic, and an occasional loose sentence prevents the style from becoming too formal and gives the reader a certain relief. Consequently, loose sentences of the type first quoted are common in easy, unstudied writing. But a writer should be careful not to construct too many of his sentences after this pattern (see Rule 14).
|
||||||
|
|
||||||
|
Two-part sentences of which the second member is introduced by *as* (in the sense of *because*), *for*, *or*, *nor*, and *while* (in the sense of *and at the same time*) likewise require a comma before the conjunction.
|
||||||
|
|
||||||
|
If the second member is introduced by an adverb, a semicolon, not a comma, is required (see Rule 5). The connectives *so* and *yet* may be used either as adverbs or as conjunctions, accordingly as the second clause is felt to be co-ordinate or subordinate; consequently either mark of punctuation may be justified. But these uses of *so* (equivalent to *accordingly* or to *so that*) are somewhat colloquial and should, as a rule, be avoided in writing. A simple correction, usually serviceable, is to omit the word *so* and begin the first clause with *as* or *since*:
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| I had never been in the place before; so I had difficulty in finding my way about. | As I had never been in the place before, I had difficulty in finding my way about. |
|
||||||
|
|
||||||
|
If a dependent clause, or an introductory phrase requiring to be set off by a comma, precedes the second independent clause, no comma is needed after the conjunction.
|
||||||
|
|
||||||
|
The situation is perilous, but if we are prepared to act promptly, there is still one chance of escape.
|
||||||
|
|
||||||
|
When the subject is the same for both clauses and is expressed only once, a comma is required if the connective is *but*. If the connective is *and*, the comma should be omitted if the relation between the two statements is close or immediate.
|
||||||
|
|
||||||
|
I have heard his arguments, but am still unconvinced.
|
||||||
|
|
||||||
|
He has had several years' experience and is thoroughly competent.
|
||||||
|
|
||||||
|
### Rule 5. Do not join independent clauses by a comma.
|
||||||
|
|
||||||
|
If two or more clauses, grammatically complete and not joined by a conjunction, are to form a single compound sentence, the proper mark of punctuation is a semicolon.
|
||||||
|
|
||||||
|
Stevenson's romances are entertaining; they are full of exciting adventures.
|
||||||
|
|
||||||
|
It is nearly half past five; we cannot reach town before dark.
|
||||||
|
|
||||||
|
It is of course equally correct to write the above as two sentences each, replacing the semicolons by periods.
|
||||||
|
|
||||||
|
Stevenson's romances are entertaining. They are full of exciting adventures.
|
||||||
|
|
||||||
|
It is nearly half past five. We cannot reach town before dark.
|
||||||
|
|
||||||
|
If a conjunction is inserted the proper mark is a comma (Rule 4).
|
||||||
|
|
||||||
|
Stevenson's romances are entertaining, for they are full of exciting adventures.
|
||||||
|
|
||||||
|
It is nearly half past five, and we cannot reach town before dark.
|
||||||
|
|
||||||
|
A comparison of the three forms given above will show clearly the advantage of the first. It is, at least in the examples given, better than the second form, because it suggests the close relationship between the two statements in a way that the second does not attempt, and better than the third, because briefer and therefore more forcible. Indeed it may be said that this simple method of indicating relationship between statements is one of the most useful devices of composition. The relationship, as above, is commonly one of cause or of consequence.
|
||||||
|
|
||||||
|
Note that if the second clause is preceded by an adverb, such as *accordingly*, *besides*, *then*, *therefore*, or *thus*, and not by a conjunction, the semicolon is still required.
|
||||||
|
|
||||||
|
Two exceptions to the rule may be admitted. If the clauses are very short, and are alike in form, a comma is usually permissible:
|
||||||
|
|
||||||
|
Man proposes, God disposes.
|
||||||
|
|
||||||
|
The gate swung apart, the bridge fell, the portcullis was drawn up.
|
||||||
|
|
||||||
|
Note that in these examples the relation is not one of cause or consequence. Also in the colloquial form of expression,
|
||||||
|
|
||||||
|
I hardly knew him, he was so changed,
|
||||||
|
|
||||||
|
a comma, not a semicolon, is required. But this form of expression is inappropriate in writing, except in the dialogue of a story or play, or perhaps in a familiar letter.
|
||||||
|
|
||||||
|
### Rule 6. Do not break sentences in two.
|
||||||
|
|
||||||
|
In other words, do not use periods for commas.
|
||||||
|
|
||||||
|
I met them on a Cunard liner several years ago. Coming home from Liverpool to New York.
|
||||||
|
|
||||||
|
He was an interesting talker. A man who had traveled all over the world and lived in half a dozen countries.
|
||||||
|
|
||||||
|
In both these examples, the first period should be replaced by a comma, and the following word begun with a small letter.
|
||||||
|
|
||||||
|
It is permissible to make an emphatic word or expression serve the purpose of a sentence and to punctuate it accordingly:
|
||||||
|
|
||||||
|
Again and again he called out. No reply.
|
||||||
|
|
||||||
|
The writer must, however, be certain that the emphasis is warranted, and that he will not be suspected of a mere blunder in syntax or in punctuation.
|
||||||
|
|
||||||
|
Rules 3, 4, 5, and 6 cover the most important principles in the punctuation of ordinary sentences; they should be so thoroughly mastered that their application becomes second nature.
|
||||||
|
|
||||||
|
### Rule 7. A participial phrase at the beginning of a sentence must refer to the grammatical subject.
|
||||||
|
|
||||||
|
Walking slowly down the road, he saw a woman accompanied by two children.
|
||||||
|
|
||||||
|
The word *walking* refers to the subject of the sentence, not to the woman. If the writer wishes to make it refer to the woman, he must recast the sentence:
|
||||||
|
|
||||||
|
He saw a woman accompanied by two children, walking slowly down the road.
|
||||||
|
|
||||||
|
Participial phrases preceded by a conjunction or by a preposition, nouns in apposition, adjectives, and adjective phrases come under the same rule if they begin the sentence.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| On arriving in Chicago, his friends met him at the station. | When he arrived (or, On his arrival) in Chicago, his friends met him at the station. |
|
||||||
|
| A soldier of proved valor, they entrusted him with the defence of the city. | A soldier of proved valor, he was entrusted with the defence of the city. |
|
||||||
|
| Young and inexperienced, the task seemed easy to me. | Young and inexperienced, I thought the task easy. |
|
||||||
|
| Without a friend to counsel him, the temptation proved irresistible. | Without a friend to counsel him, he found the temptation irresistible. |
|
||||||
|
|
||||||
|
Sentences violating this rule are often ludicrous.
|
||||||
|
|
||||||
|
Being in a dilapidated condition, I was able to buy the house very cheap.
|
||||||
|
|
||||||
|
Wondering irresolutely what to do next, the clock struck twelve.
|
||||||
+398
@@ -0,0 +1,398 @@
|
|||||||
|
## III. Elementary Principles Of Composition
|
||||||
|
|
||||||
|
### Rule 8. Make the paragraph the unit of composition: one paragraph to each topic.
|
||||||
|
|
||||||
|
If the subject on which you are writing is of slight extent, or if you intend to treat it very briefly, there may be no need of subdividing it into topics. Thus a brief description, a brief summary of a literary work, a brief account of a single incident, a narrative merely outlining an action, the setting forth of a single idea, any one of these is best written in a single paragraph. After the paragraph has been written, examine it to see whether subdivision will not improve it.
|
||||||
|
|
||||||
|
Ordinarily, however, a subject requires subdivision into topics, each of which should be made the subject of a paragraph. The object of treating each topic in a paragraph by itself is, of course, to aid the reader. The beginning of each paragraph is a signal to him that a new step in the development of the subject has been reached.
|
||||||
|
|
||||||
|
The extent of subdivision will vary with the length of the composition. For example, a short notice of a book or poem might consist of a single paragraph. One slightly longer might consist of two paragraphs:
|
||||||
|
|
||||||
|
- A. Account of the work.
|
||||||
|
- B. Critical discussion.
|
||||||
|
|
||||||
|
A report on a poem, written for a class in literature, might consist of seven paragraphs:
|
||||||
|
|
||||||
|
- A. Facts of composition and publication.
|
||||||
|
- B. Kind of poem; metrical form.
|
||||||
|
- C. Subject.
|
||||||
|
- D. Treatment of subject.
|
||||||
|
- E. For what chiefly remarkable.
|
||||||
|
- F. Wherein characteristic of the writer.
|
||||||
|
- G. Relationship to other works.
|
||||||
|
|
||||||
|
The contents of paragraphs C and D would vary with the poem. Usually, paragraph C would indicate the actual or imagined circumstances of the poem (the situation), if these call for explanation, and would then state the subject and outline its development. If the poem is a narrative in the third person throughout, paragraph C need contain no more than a concise summary of the action. Paragraph D would indicate the leading ideas and show how they are made prominent, or would indicate what points in the narrative are chiefly emphasized.
|
||||||
|
|
||||||
|
A novel might be discussed under the heads:
|
||||||
|
|
||||||
|
- A. Setting.
|
||||||
|
- B. Plot.
|
||||||
|
- C. Characters.
|
||||||
|
- D. Purpose.
|
||||||
|
|
||||||
|
An historical event might be discussed under the heads:
|
||||||
|
|
||||||
|
- A. What led up to the event.
|
||||||
|
- B. Account of the event.
|
||||||
|
- C. What the event led up to.
|
||||||
|
|
||||||
|
In treating either of these last two subjects, the writer would probably find it necessary to subdivide one or more of the topics here given.
|
||||||
|
|
||||||
|
As a rule, single sentences should not be written or printed as paragraphs. An exception may be made of sentences of transition, indicating the relation between the parts of an exposition or argument. Frequent exceptions are also necessary in textbooks, guidebooks, and other works in which many topics are treated briefly.
|
||||||
|
|
||||||
|
In dialogue, each speech, even if only a single word, is a paragraph by itself; that is, a new paragraph begins with each change of speaker. The application of this rule, when dialogue and narrative are combined, is best learned from examples in well-printed works of fiction.
|
||||||
|
|
||||||
|
### Rule 9. As a rule, begin each paragraph with a topic sentence, end it in conformity with the beginning.
|
||||||
|
|
||||||
|
Again, the object is to aid the reader. The practice here recommended enables him to discover the purpose of each paragraph as he begins to read it, and to retain this purpose in mind as he ends it. For this reason, the most generally useful kind of paragraph, particularly in exposition and argument, is that in which
|
||||||
|
|
||||||
|
\(a\) the topic sentence comes at or near the beginning;
|
||||||
|
|
||||||
|
\(b\) the succeeding sentences explain or establish or develop the statement made in the topic sentence; and
|
||||||
|
|
||||||
|
\(c\) the final sentence either emphasizes the thought of the topic sentence or states some important consequence.
|
||||||
|
|
||||||
|
Ending with a digression, or with an unimportant detail, is particularly to be avoided.
|
||||||
|
|
||||||
|
If the paragraph forms part of a larger composition, its relation to what precedes, or its function as a part of the whole, may need to be expressed. This can sometimes be done by a mere word or phrase (*again*; *therefore*; *for the same reason*) in the topic sentence. Sometimes, however, it is expedient to precede the topic sentence by one or more sentences of introduction or transition. If more than one such sentence is required, it is generally better to set apart the transitional sentences as a separate paragraph.
|
||||||
|
|
||||||
|
According to the writer's purpose, he may, as indicated above, relate the body of the paragraph to the topic sentence in one or more of several different ways. He may make the meaning of the topic sentence clearer by restating it in other forms, by defining its terms, by denying the contrary, by giving illustrations or specific instances; he may establish it by proofs; or he may develop it by showing its implications and consequences. In a long paragraph, he may carry out several of these processes.
|
||||||
|
|
||||||
|
1 Now, to be properly enjoyed, a walking tour should be gone upon alone. 2 If you go in a company, or even in pairs, it is no longer a walking tour in anything but name; it is something else and more in the nature of a picnic. 3 A walking tour should be gone upon alone, because freedom is of the essence; because you should be able to stop and go on, and follow this way or that, as the freak takes you; and because you must have your own pace, and neither trot alongside a champion walker, nor mince in time with a girl. 4 And you must be open to all impressions and let your thoughts take colour from what you see. 5 You should be as a pipe for any wind to play upon. 6 “I cannot see the wit,” says Hazlitt, “of walking and talking at the same time. 7 When I am in the country, I wish to vegetate like the country,” which is the gist of all that can be said upon the matter. 8 There should be no cackle of voices at your elbow, to jar on the meditative silence of the morning. 9 And so long as a man is reasoning he cannot surrender himself to that fine intoxication that comes of much motion in the open air, that begins in a sort of dazzle and sluggishness of the brain, and ends in a peace that passes comprehension.—Stevenson, Walking Tours.
|
||||||
|
|
||||||
|
1 Topic sentence. 2 The meaning made clearer by denial of the contrary. 3 The topic sentence repeated, in abridged form, and supported by three reasons; the meaning of the third (“you must have your own pace”) made clearer by denying the contrary. 4 A fourth reason, stated in two forms. 5 The same reason, stated in still another form. 6–7 The same reason as stated by Hazlitt. 8 Repetition, in paraphrase, of the quotation from Hazlitt. 9 Final statement of the fourth reason, in language amplified and heightened to form a strong conclusion.
|
||||||
|
|
||||||
|
1 It was chiefly in the eighteenth century that a very different conception of history grew up. 2 Historians then came to believe that their task was not so much to paint a picture as to solve a problem; to explain or illustrate the successive phases of national growth, prosperity, and adversity. 3 The history of morals, of industry, of intellect, and of art; the changes that take place in manners or beliefs; the dominant ideas that prevailed in successive periods; the rise, fall, and modification of political constitutions; in a word, all the conditions of national well-being became the subject of their works. 4 They sought rather to write a history of peoples than a history of kings. 5 They looked especially in history for the chain of causes and effects. 6 They undertook to study in the past the physiology of nations, and hoped by applying the experimental method on a large scale to deduce some lessons of real value about the conditions on which the welfare of society mainly depend.—Lecky, The Political Value of History.
|
||||||
|
|
||||||
|
1 Topic sentence. 2 The meaning of the topic sentence made clearer; the new conception of history defined. 3 The definition expanded. 4 The definition explained by contrast. 5 The definition supplemented: another element in the new conception of history. 6 Conclusion: an important consequence of the new conception of history.
|
||||||
|
|
||||||
|
In narration and description the paragraph sometimes begins with a concise, comprehensive statement serving to hold together the details that follow.
|
||||||
|
|
||||||
|
The breeze served us admirably.
|
||||||
|
|
||||||
|
The campaign opened with a series of reverses.
|
||||||
|
|
||||||
|
The next ten or twelve pages were filled with a curious set of entries.
|
||||||
|
|
||||||
|
But this device, if too often used, would become a mannerism. More commonly the opening sentence simply indicates by its subject with what the paragraph is to be principally concerned.
|
||||||
|
|
||||||
|
At length I thought I might return towards the stockade.
|
||||||
|
|
||||||
|
He picked up the heavy lamp from the table and began to explore.
|
||||||
|
|
||||||
|
Another flight of steps, and they emerged on the roof.
|
||||||
|
|
||||||
|
The brief paragraphs of animated narrative, however, are often without even this semblance of a topic sentence. The break between them serves the purpose of a rhetorical pause, throwing into prominence some detail of the action.
|
||||||
|
|
||||||
|
### Rule 10. Use the active voice.
|
||||||
|
|
||||||
|
The active voice is usually more direct and vigorous than the passive:
|
||||||
|
|
||||||
|
I shall always remember my first visit to Boston.
|
||||||
|
|
||||||
|
This is much better than
|
||||||
|
|
||||||
|
My first visit to Boston will always be remembered by me.
|
||||||
|
|
||||||
|
The latter sentence is less direct, less bold, and less concise. If the writer tries to make it more concise by omitting “by me,”
|
||||||
|
|
||||||
|
My first visit to Boston will always be remembered,
|
||||||
|
|
||||||
|
it becomes indefinite: is it the writer, or some person undisclosed, or the world at large, that will always remember this visit?
|
||||||
|
|
||||||
|
This rule does not, of course, mean that the writer should entirely discard the passive voice, which is frequently convenient and sometimes necessary.
|
||||||
|
|
||||||
|
The dramatists of the Restoration are little esteemed to-day.
|
||||||
|
|
||||||
|
Modern readers have little esteem for the dramatists of the Restoration.
|
||||||
|
|
||||||
|
The first would be the right form in a paragraph on the dramatists of the Restoration; the second, in a paragraph on the tastes of modern readers. The need of making a particular word the subject of the sentence will often, as in these examples, determine which voice is to be used.
|
||||||
|
|
||||||
|
As a rule, avoid making one passive depend directly upon another.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Gold was not allowed to be exported. | It was forbidden to export gold (The export of gold was prohibited). |
|
||||||
|
| He has been proved to have been seen entering the building. | It has been proved that he was seen to enter the building. |
|
||||||
|
|
||||||
|
In both the examples above, before correction, the word properly related to the second passive is made the subject of the first.
|
||||||
|
|
||||||
|
A common fault is to use as the subject of a passive construction a noun which expresses the entire action, leaving to the verb no function beyond that of completing the sentence.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A survey of this region was made in 1900. | This region was surveyed in 1900. |
|
||||||
|
| Mobilization of the army was rapidly effected. | The army was rapidly mobilized. |
|
||||||
|
| Confirmation of these reports cannot be obtained. | These reports cannot be confirmed. |
|
||||||
|
|
||||||
|
Compare the _sentence,_ “The export of gold was prohibited,” in which the predicate “was prohibited” expresses something not implied in “export.”
|
||||||
|
|
||||||
|
The habitual use of the active voice makes for forcible writing. This is true not only in narrative principally concerned with action, but in writing of any kind. Many a tame sentence of description or exposition can be made lively and emphatic by substituting a verb in the active voice for some such perfunctory expression as *there is*, or *could be heard*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| There were a great number of dead leaves lying on the ground. | Dead leaves covered the ground. |
|
||||||
|
| The sound of a guitar somewhere in the house could be heard. | Somewhere in the house a guitar hummed sleepily. |
|
||||||
|
| The reason that he left college was that his health became impaired. | Failing health compelled him to leave college. |
|
||||||
|
| It was not long before he was very sorry that he had said what he had. | He soon repented his words. |
|
||||||
|
|
||||||
|
### Rule 11. Put statements in positive form.
|
||||||
|
|
||||||
|
Make definite assertions. Avoid tame, colorless, hesitating, non-committal language. Use the word *not* as a means of denial or in antithesis, never as a means of evasion.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| He was not very often on time. | He usually came late. |
|
||||||
|
| He did not think that studying Latin was much use. | He thought the study of Latin useless. |
|
||||||
|
| The Taming of the Shrew is rather weak in spots. Shakespeare does not portray Katharine as a very admirable character, nor does Bianca remain long in memory as an important character in Shakespeare's works. | The women in The Taming of the Shrew are unattractive. Katharine is disagreeable, Bianca insignificant. |
|
||||||
|
|
||||||
|
The last example, before correction, is indefinite as well as negative. The corrected version, consequently, is simply a guess at the writer's intention.
|
||||||
|
|
||||||
|
All three examples show the weakness inherent in the word *not*. Consciously or unconsciously, the reader is dissatisfied with being told only what is not; he wishes to be told what is. Hence, as a rule, it is better to express even a negative in positive form.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| not honest | dishonest |
|
||||||
|
| not important | trifling |
|
||||||
|
| did not remember | forgot |
|
||||||
|
| did not pay any attention to | ignored |
|
||||||
|
| did not have much confidence in | distrusted |
|
||||||
|
|
||||||
|
The antithesis of negative and positive is strong:
|
||||||
|
|
||||||
|
Not charity, but simple justice.
|
||||||
|
|
||||||
|
Not that I loved Caesar less, but Rome the more.
|
||||||
|
|
||||||
|
Negative words other than *not* are usually strong:
|
||||||
|
|
||||||
|
The sun never sets upon the British flag.
|
||||||
|
|
||||||
|
### Rule 12. Use definite, specific, concrete language.
|
||||||
|
|
||||||
|
Prefer the specific to the general, the definite to the vague, the concrete to the abstract.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A period of unfavorable weather set in. | It rained every day for a week. |
|
||||||
|
| He showed satisfaction as he took possession of his well-earned reward. | He grinned as he pocketed the coin. |
|
||||||
|
| There is a general agreement among those who have enjoyed the experience that surf-riding is productive of great exhilaration. | All who have tried surf-riding agree that it is most exhilarating. |
|
||||||
|
|
||||||
|
If those who have studied the art of writing are in accord on any one point, it is on this, that the surest method of arousing and holding the attention of the reader is by being specific, definite, and concrete. Critics have pointed out how much of the effectiveness of the greatest writers, Homer, Dante, Shakespeare, results from their constant definiteness and concreteness. Browning, to cite a more modern author, affords many striking examples. Take, for instance, the lines from My Last Duchess,
|
||||||
|
|
||||||
|
Sir, 'twas all one! My favour at her breast,
|
||||||
|
|
||||||
|
The dropping of the daylight in the west,
|
||||||
|
|
||||||
|
The bough of cherries some officious fool
|
||||||
|
|
||||||
|
Broke in the orchard for her, the white mule
|
||||||
|
|
||||||
|
She rode with round the terrace—all and each
|
||||||
|
|
||||||
|
Would draw from her alike the approving speech,
|
||||||
|
|
||||||
|
Or blush, at least,
|
||||||
|
|
||||||
|
and those which end the poem,
|
||||||
|
|
||||||
|
Notice Neptune, though,
|
||||||
|
|
||||||
|
Taming a sea-horse, thought a rarity,
|
||||||
|
|
||||||
|
Which Claus of Innsbruck cast in bronze for me.
|
||||||
|
|
||||||
|
These words call up pictures. Recall how in The Bishop Orders his Tomb in St. Praxed's Church “the Renaissance spirit—its worldliness, inconsistency, pride, hypocrisy, ignorance of itself, love of art, of luxury, of good Latin,” to quote Ruskin's comment on the poem, is made manifest in specific details and in concrete terms.
|
||||||
|
|
||||||
|
Prose, in particular narrative and descriptive prose, is made vivid by the same means. If the experiences of Jim Hawkins and of David Balfour, of Kim, of Nostromo, have seemed for the moment real to countless readers, if in reading Carlyle we have almost the sense of being physically present at the taking of the Bastille, it is because of the definiteness of the details and the concreteness of the terms used. It is not that every detail is given; that would be impossible, as well as to no purpose; but that all the significant details are given, and not vaguely, but with such definiteness that the reader, in imagination, can project himself into the scene.
|
||||||
|
|
||||||
|
In exposition and in argument, the writer must likewise never lose his hold upon the concrete, and even when he is dealing with general principles, he must give particular instances of their application.
|
||||||
|
|
||||||
|
“This superiority of specific expressions is clearly due to the effort required to translate words into thoughts. As we do not think in generals, but in particulars—as whenever any class of things is referred to, we represent it to ourselves by calling to mind individual members of it, it follows that when an abstract word is used, the hearer or reader has to choose, from his stock of images, one or more by which he may figure to himself the genus mentioned. In doing this, some delay must arise, some force be expended; and if by employing a specific term an appropriate image can be at once suggested, an economy is achieved, and a more vivid impression produced.”
|
||||||
|
|
||||||
|
Herbert Spencer, from whose Philosophy of Style the preceding paragraph is quoted, illustrates the principle by the sentences:
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| In proportion as the manners, customs, and amusements of a nation are cruel and barbarous, the regulations of their penal code will be severe. | In proportion as men delight in battles, bull-fights, and combats of gladiators, will they punish by hanging, burning, and the rack. |
|
||||||
|
|
||||||
|
### Rule 13. Omit needless words.
|
||||||
|
|
||||||
|
Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that he make every word tell.
|
||||||
|
|
||||||
|
Many expressions in common use violate this principle:
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| the question as to whether | whether (the question whether) |
|
||||||
|
| there is no doubt but that | no doubt (doubtless) |
|
||||||
|
| used for fuel purposes | used for fuel |
|
||||||
|
| he is a man who | he |
|
||||||
|
| in a hasty manner | hastily |
|
||||||
|
| this is a subject which | this subject |
|
||||||
|
| His story is a strange one. | His story is strange. |
|
||||||
|
|
||||||
|
In especial the expression *the fact that* should be revised out of every sentence in which it occurs.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| owing to the fact that | since (because) |
|
||||||
|
| in spite of the fact that | though (although) |
|
||||||
|
| call your attention to the fact that | remind you (notify you) |
|
||||||
|
| I was unaware of the fact that | I was unaware that (did not know) |
|
||||||
|
| the fact that he had not succeeded | his failure |
|
||||||
|
| the fact that I had arrived | my arrival |
|
||||||
|
|
||||||
|
See also under *case*, *character*, *nature*, *system* in Chapter V.
|
||||||
|
|
||||||
|
*Who is*, *which was*, and the like are often superfluous.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| His brother, who is a member of the same firm | His brother, a member of the same firm |
|
||||||
|
| Trafalgar, which was Nelson's last battle | Trafalgar, Nelson's last battle |
|
||||||
|
|
||||||
|
As positive statement is more concise than negative, and the active voice more concise than the passive, many of the examples given under Rules 11 and 12 illustrate this rule as well.
|
||||||
|
|
||||||
|
A common violation of conciseness is the presentation of a single complex idea, step by step, in a series of sentences or independent clauses which might to advantage be combined into one.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Macbeth was very ambitious. This led him to wish to become king of Scotland. The witches told him that this wish of his would come true. The king of Scotland at this time was Duncan. Encouraged by his wife, Macbeth murdered Duncan. He was thus enabled to succeed Duncan as king. (51 words.) | Encouraged by his wife, Macbeth achieved his ambition and realized the prediction of the witches by murdering Duncan and becoming king of Scotland in his place. (26 words.) |
|
||||||
|
| There were several less important courses, but these were the most important, and although they did not come every day, they came often enough to keep you in such a state of mind that you never knew what your next move would be. (43 words.) | These, the most important courses of all, came, if not daily, at least often enough to keep one under constant strain. (21 words.) |
|
||||||
|
|
||||||
|
### Rule 14. Avoid a succession of loose sentences
|
||||||
|
|
||||||
|
This rule refers especially to loose sentences of a particular type, those consisting of two co-ordinate clauses, the second introduced by a conjunction or relative. Although single sentences of this type may be unexceptionable (see under Rule 4), a series soon becomes monotonous and tedious.
|
||||||
|
|
||||||
|
An unskilful writer will sometimes construct a whole paragraph of sentences of this kind, using as connectives *and*, *but*, *so*, and less frequently, *who*, *which*, *when*, *where*, and *while*, these last in non-restrictive senses (see under Rule 3).
|
||||||
|
|
||||||
|
The third concert of the subscription series was given last evening, and a large audience was in attendance. Mr. Edward Appleton was the soloist, and the Boston Symphony Orchestra furnished the instrumental music. The former showed himself to be an artist of the first rank, while the latter proved itself fully deserving of its high reputation. The interest aroused by the series has been very gratifying to the Committee, and it is planned to give a similar series annually hereafter. The fourth concert will be given on Tuesday, May 10, when an equally attractive programme will be presented.
|
||||||
|
|
||||||
|
Apart from its triteness and emptiness, the paragraph above is weak because of the structure of its sentences, with their mechanical symmetry and sing-song. Contrast with them the sentences in the paragraphs quoted under Rule 9, or in any piece of good English prose, as the preface (Before the Curtain) to Vanity Fair.
|
||||||
|
|
||||||
|
If the writer finds that he has written a series of sentences of the type described, he should recast enough of them to remove the monotony, replacing them by simple sentences, by sentences of two clauses joined by a semicolon, by periodic sentences of two clauses, by sentences, loose or periodic, of three clauses—whichever best represent the real relations of the thought.
|
||||||
|
|
||||||
|
### Rule 15. Express co-ordinate ideas in similar form.
|
||||||
|
|
||||||
|
This principle, that of parallel construction, requires that expressions of similar content and function should be outwardly similar. The likeness of form enables the reader to recognize more readily the likeness of content and function. Familiar instances from the Bible are the Ten Commandments, the Beatitudes, and the petitions of the Lord's Prayer.
|
||||||
|
|
||||||
|
The unskillful writer often violates this principle, from a mistaken belief that he should constantly vary the form of his expressions. It is true that in repeating a statement in order to emphasize it he may have need to vary its form. For illustration, see the paragraph from Stevenson quoted under Rule _9_. But apart from this, he should follow the principle of parallel construction.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Formerly, science was taught by the textbook method, while now the laboratory method is employed. | Formerly, science was taught by the textbook method; now it is taught by the laboratory method. |
|
||||||
|
|
||||||
|
The left-hand version gives the impression that the writer is undecided or timid; he seems unable or afraid to choose one form of expression and hold to it. The right-hand version shows that the writer has at least made his choice and abided by it.
|
||||||
|
|
||||||
|
By this principle, an article or a preposition applying to all the members of a series must either be used only before the first term or else be repeated before each term.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| The French, the Italians, Spanish, and Portuguese | The French, the Italians, the Spanish, and the Portuguese |
|
||||||
|
| In spring, summer, or in winter | In spring, summer, or winter (In spring, in summer, or in winter) |
|
||||||
|
|
||||||
|
Correlative expressions (*both, and*; *not, but*; *not only, but also*; *either, or*; *first, second, third*; and the like) should be followed by the same grammatical construction, that is, virtually, by the same part of speech. (Such combinations as “both Henry and I,” “not silk, but a cheap substitute,” are obviously within the rule.) Many violations of this rule (as the first three below) arise from faulty arrangement; others (as the last) from the use of unlike constructions.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| It was both a long ceremony and very tedious. | The ceremony was both long and tedious. |
|
||||||
|
| A time not for words, but action. | A time not for words, but for action. |
|
||||||
|
| Either you must grant his request or incur his ill will. | You must either grant his request or incur his ill will. |
|
||||||
|
| My objections are, first, the injustice of the measure; second, that it is unconstitutional. | My objections are, first, that the measure is unjust; second, that it is unconstitutional. |
|
||||||
|
|
||||||
|
See also the third example under Rule 12 and the last under Rule 13.
|
||||||
|
|
||||||
|
It may be asked, what if a writer needs to express a very large number of similar ideas, say twenty? Must he write twenty consecutive sentences of the same pattern? On closer examination he will probably find that the difficulty is imaginary, that his twenty ideas can be classified in groups, and that he need apply the principle only within each group. Otherwise he had best avoid difficulty by putting his statements in the form of a table.
|
||||||
|
|
||||||
|
### Rule 16. Keep related words together.
|
||||||
|
|
||||||
|
The position of the words in a sentence is the principal means of showing their relationship. The writer must therefore, so far as possible, bring together the words, and groups of words, that are related in thought, and keep apart those which are not so related.
|
||||||
|
|
||||||
|
The subject of a sentence and the principal verb should not, as a rule, be separated by a phrase or clause that can be transferred to the beginning.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Wordsworth, in the fifth book of The Excursion, gives a minute description of this church. | In the fifth book of The Excursion, Wordsworth gives a minute description of this church. |
|
||||||
|
| Cast iron, when treated in a Bessemer converter, is changed into steel. | By treatment in a Bessemer converter, cast iron is changed into steel. |
|
||||||
|
|
||||||
|
The objection is that the interposed phrase or clause needlessly interrupts the natural order of the main clause. Usually, however, this objection does not hold when the order is interrupted only by a relative clause or by an expression in apposition. Nor does it hold in periodic sentences in which the interruption is a deliberately used means of creating suspense (see examples under Rule 18).
|
||||||
|
|
||||||
|
The relative pronoun should come, as a rule, immediately after its antecedent.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| There was a look in his eye that boded mischief. | In his eye was a look that boded mischief. |
|
||||||
|
| He wrote three articles about his adventures in Spain, which were published in Harper's Magazine. | He published in Harper's Magazine three articles about his adventures in Spain. |
|
||||||
|
| This is a portrait of Benjamin Harrison, grandson of William Henry Harrison, who became President in 1889. | This is a portrait of Benjamin Harrison, grandson of William Henry Harrison. He became President in 1889. |
|
||||||
|
|
||||||
|
If the antecedent consists of a group of words, the relative comes at the end of the group, unless this would cause ambiguity.
|
||||||
|
|
||||||
|
The Superintendent of the Chicago Division, who
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A proposal to amend the Sherman Act, which has been variously judged. | A proposal, which has been variously judged, to amend the Sherman Act. |
|
||||||
|
| — | A proposal to amend the much-debated Sherman Act. |
|
||||||
|
| The grandson of William Henry Harrison, who | William Henry Harrison's grandson, who |
|
||||||
|
|
||||||
|
A noun in apposition may come between antecedent and relative, because in such a combination no real ambiguity can arise.
|
||||||
|
|
||||||
|
The Duke of York, his brother, who was regarded with hostility by the Whigs
|
||||||
|
|
||||||
|
Modifiers should come, if possible, next to the word they modify. If several expressions modify the same word, they should be so arranged that no wrong relation is suggested.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| All the members were not present. | Not all the members were present. |
|
||||||
|
| He only found two mistakes. | He found only two mistakes. |
|
||||||
|
| Major R. E. Joyce will give a lecture on Tuesday evening in Bailey Hall, to which the public is invited, on “My Experiences in Mesopotamia” at eight P. M. | On Tuesday evening at eight P. M., Major R. E. Joyce will give in Bailey Hall a lecture on “My Experiences in Mesopotamia.” The public is invited. |
|
||||||
|
|
||||||
|
### Rule 17. In summaries, keep to one tense.
|
||||||
|
|
||||||
|
In summarizing the action of a drama, the writer should always use the present tense. In summarizing a poem, story, or novel, he should preferably use the present, though he may use the past if he prefers. If the summary is in the present tense, antecedent action should be expressed by the perfect; if in the past, by the past perfect.
|
||||||
|
|
||||||
|
An unforeseen chance prevents Friar John from delivering Friar Lawrence's letter to Romeo. Meanwhile, owing to her father's arbitrary change of the day set for her wedding, Juliet has been compelled to drink the potion on Tuesday night, with the result that Balthasar informs Romeo of her supposed death before Friar Lawrence learns of the non-delivery of the letter.
|
||||||
|
|
||||||
|
But whichever tense be used in the summary, a past tense in indirect discourse or in indirect question remains unchanged.
|
||||||
|
|
||||||
|
The Friar confesses that it was he who married them.
|
||||||
|
|
||||||
|
Apart from the exceptions noted, whichever tense the writer chooses, he should use throughout. Shifting from one tense to the other gives the appearance of uncertainty and irresolution (compare Rule 15).
|
||||||
|
|
||||||
|
In presenting the statements or the thought of some one else, as in summarizing an essay or reporting a speech, the writer should avoid intercalating such expressions as “he said,” “he stated,” “the speaker added,” “the speaker then went on to say,” “the author also thinks,” or the like. He should indicate clearly at the outset, once for all, that what follows is summary, and then waste no words in repeating the notification.
|
||||||
|
|
||||||
|
In notebooks, in newspapers, in handbooks of literature, summaries of one kind or another may be indispensable, and for children in primary schools it is a useful exercise to retell a story in their own words. But in the criticism or interpretation of literature the writer should be careful to avoid dropping into summary. He may find it necessary to devote one or two sentences to indicating the subject, or the opening situation, of the work he is discussing; he may cite numerous details to illustrate its qualities. But he should aim to write an orderly discussion supported by evidence, not a summary with occasional comment. Similarly, if the scope of his discussion includes a number of works, he will as a rule do better not to take them up singly in chronological order, but to aim from the beginning at establishing general conclusions.
|
||||||
|
|
||||||
|
### Rule 18. Place the emphatic words of a sentence at the end.
|
||||||
|
|
||||||
|
The proper place in the sentence for the word, or group of words, which the writer desires to make most prominent is usually the end.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Humanity has hardly advanced in fortitude since that time, though it has advanced in many other ways. | Humanity, since that time, has advanced in many other ways, but it has hardly advanced in fortitude. |
|
||||||
|
| This steel is principally used for making razors, because of its hardness. | Because of its hardness, this steel is principally used in making razors. |
|
||||||
|
|
||||||
|
The word or group of words entitled to this position of prominence is usually the logical predicate, that is, the *new* element in the sentence, as it is in the second example.
|
||||||
|
|
||||||
|
The effectiveness of the periodic sentence arises from the prominence which it gives to the main statement.
|
||||||
|
|
||||||
|
Four centuries ago, Christopher Columbus, one of the Italian mariners whom the decline of their own republics had put at the service of the world and of adventure, seeking for Spain a westward passage to the Indies as a set-off against the achievements of Portuguese discoverers, lighted on America.
|
||||||
|
|
||||||
|
With these hopes and in this belief I would urge you, laying aside all hindrance, thrusting away all private aims, to devote yourself unswervingly and unflinchingly to the vigorous and successful prosecution of this war.
|
||||||
|
|
||||||
|
The other prominent position in the sentence is the beginning. Any element in the sentence, other than the subject, may become emphatic when placed first.
|
||||||
|
|
||||||
|
Deceit or treachery he could never forgive.
|
||||||
|
|
||||||
|
So vast and rude, fretted by the action of nearly three thousand years, the fragments of this architecture may often seem, at first sight, like works of nature.
|
||||||
|
|
||||||
|
A subject coming first in its sentence may be emphatic, but hardly by its position alone. In the sentence,
|
||||||
|
|
||||||
|
Great kings worshipped at his shrine,
|
||||||
|
|
||||||
|
the emphasis upon *kings* arises largely from its meaning and from the context. To receive special emphasis, the subject of a sentence must take the position of the predicate.
|
||||||
|
|
||||||
|
Through the middle of the valley flowed a winding stream.
|
||||||
|
|
||||||
|
The principle that the proper place for what is to be made most prominent is the end applies equally to the words of a sentence, to the sentences of a paragraph, and to the paragraphs of a composition.
|
||||||
+89
@@ -0,0 +1,89 @@
|
|||||||
|
## IV. A Few Matters of Form
|
||||||
|
|
||||||
|
**Headings.** Leave a blank line, or its equivalent in space, after the title or heading of a manuscript. On succeeding pages, if using ruled paper, begin on the first line.
|
||||||
|
|
||||||
|
**Numerals.** Do not spell out dates or other serial numbers. Write them in figures or in Roman notation, as may be appropriate.
|
||||||
|
|
||||||
|
August 9, 1918 (9 August 1918)
|
||||||
|
|
||||||
|
Rule 3
|
||||||
|
|
||||||
|
Chapter XII
|
||||||
|
|
||||||
|
352nd Infantry
|
||||||
|
|
||||||
|
**Parentheses.** A sentence containing an expression in parenthesis is punctuated, outside of the marks of parenthesis, exactly as if the expression in parenthesis were absent. The expression within is punctuated as if it stood by itself, except that the final stop is omitted unless it is a question mark or an exclamation point.
|
||||||
|
|
||||||
|
I went to his house yesterday (my third attempt to see him), but he had left town.
|
||||||
|
|
||||||
|
He declares (and why should we doubt his good faith?) that he is now certain of success.
|
||||||
|
|
||||||
|
(When a wholly detached expression or sentence is parenthesized, the final stop comes before the last mark of parenthesis.)
|
||||||
|
|
||||||
|
**Quotations.** Formal quotations, cited as documentary evidence, are introduced by a colon and enclosed in quotation marks.
|
||||||
|
|
||||||
|
The provision of the Constitution is: “No tax or duty shall be laid on articles exported from any state.”
|
||||||
|
|
||||||
|
Quotations grammatically in apposition or the direct objects of verbs are preceded by a comma and enclosed in quotation marks.
|
||||||
|
|
||||||
|
[](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "34")I recall the maxim of La Rochefoucauld, “Gratitude is a lively sense of benefits to come.”
|
||||||
|
|
||||||
|
Aristotle says, “Art is an imitation of nature.”
|
||||||
|
|
||||||
|
Quotations of an entire line, or more, of verse, are begun on a fresh line and centered, but need not be enclosed in quotation marks.
|
||||||
|
|
||||||
|
Wordsworth's enthusiasm for the Revolution was at first unbounded:
|
||||||
|
|
||||||
|
Bliss was it in that dawn to be alive,
|
||||||
|
|
||||||
|
But to be young was very heaven!
|
||||||
|
|
||||||
|
Quotations introduced by _that_ are regarded as in indirect discourse and not enclosed in quotation marks.
|
||||||
|
|
||||||
|
Keats declares that beauty is truth, truth beauty.
|
||||||
|
|
||||||
|
Proverbial expressions and familiar phrases of literary origin require no quotation marks.
|
||||||
|
|
||||||
|
These are the times that try men's souls.
|
||||||
|
|
||||||
|
He lives far from the madding crowd.
|
||||||
|
|
||||||
|
The same is true of colloquialisms and slang.
|
||||||
|
|
||||||
|
**References.** In scholarly work requiring exact references, abbreviate titles that occur frequently, giving the full forms in an alphabetical list at the end. As a general practice, give the references in parenthesis or in footnotes, not in the body of the sentence. Omit the words _act_, _scene_, _line_, _book_, _volume_, _page_, except when referring by only one of them. Punctuate as indicated below.
|
||||||
|
|
||||||
|
In the second scene of the third act In III.ii (still better, simply insert III.ii in parenthesis at the proper place in the sentence)
|
||||||
|
|
||||||
|
After the killing of Polonius, Hamlet is placed under guard (IV.ii. 14).
|
||||||
|
|
||||||
|
2 Samuel i:17–27
|
||||||
|
|
||||||
|
Othello II.iii. 264–267, III.iii. 155–161.
|
||||||
|
|
||||||
|
**Syllabication.** If there is room at the end of a line for one or more syllables of a word, but not for the whole word, divide the word, unless this involves cutting off only a [](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm "35") single letter, or cutting off only two letters of a long word. No hard and fast rule for all words can be laid down. The principles most frequently applicable are:
|
||||||
|
|
||||||
|
(a) Divide the word according to its formation:
|
||||||
|
|
||||||
|
know-ledge (not knowl-edge); Shake-speare (not Shakes-peare); de-scribe (not des-cribe); atmo-sphere (not atmos-phere);
|
||||||
|
|
||||||
|
(b) Divide “on the vowel:”
|
||||||
|
|
||||||
|
edi-ble (not ed-ible); propo-sition; ordi-nary; espe-cial; reli-gious; oppo-nents; regu-lar; classi-fi-ca-tion (three divisions allowable); deco-rative; presi-dent;
|
||||||
|
|
||||||
|
(c) Divide between double letters, unless they come at the end of the simple form of the word:
|
||||||
|
|
||||||
|
Apen-nines; Cincin-nati; refer-ring; but tell-ing.
|
||||||
|
|
||||||
|
(d) Do not divide before final _-ed_ if the _e_ is silent:
|
||||||
|
|
||||||
|
treat-ed (but not roam-ed or nam-ed).
|
||||||
|
|
||||||
|
The treatment of consonants in combination is best shown from examples:
|
||||||
|
|
||||||
|
for-tune; pic-ture; sin-gle; presump-tuous; illus-tration; sub-stan-tial (either division); indus-try; instruc-tion; sug-ges-tion; incen-diary.
|
||||||
|
|
||||||
|
The student will do well to examine the syllable-division in a number of pages of any carefully printed book.
|
||||||
|
|
||||||
|
**Titles.** For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial _A_ or _The_ from titles when you place the possessive before them.
|
||||||
|
|
||||||
|
The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities; Dickens's Tale of Two Cities.
|
||||||
+348
@@ -0,0 +1,348 @@
|
|||||||
|
## V. Words And Expressions Commonly Misused
|
||||||
|
|
||||||
|
(Some of the forms here listed, as *like I did*, are downright bad English; others, as the split infinitive, have their defenders, but are in such general disfavor that it is at least inadvisable to use them; still others, as *case*, *factor*, *feature*, *interesting*, *one of the most*, are good in their place, but are constantly obtruding themselves into places where they have no right to be. If the writer will make it his purpose from the beginning to express accurately his own individual thought, and will refuse to be satisfied with a ready-made formula that saves him the trouble of doing so, this last set of expressions will cause him little trouble. But if he finds that in a moment of inadvertence he has used one of them, his proper course will probably be not to patch up the sentence by substituting one word or set of words for another, but to recast it completely, as illustrated in a number of examples below and in others under Rules 12 and 13.)
|
||||||
|
|
||||||
|
**All right.** Idiomatic in familiar speech as a detached phrase in the sense, “Agreed,” or “Go ahead.” In other uses better avoided. Always written as two words.
|
||||||
|
|
||||||
|
**As good or better than.** Expressions of this type should be corrected by rearranging the sentence.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| My opinion is as good or better than his. | My opinion is as good as his, or better (if not better). |
|
||||||
|
|
||||||
|
**As to whether.** *Whether* is sufficient; see under Rule 13.
|
||||||
|
|
||||||
|
**Bid.** Takes the infinitive without *to*. The past tense in the sense, _“ordered,”_ is *bade*.
|
||||||
|
|
||||||
|
**But.** Unnecessary after *doubt* and *help*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| I have no doubt but that | I have no doubt that |
|
||||||
|
| He could not help see but that | He could not help seeing that |
|
||||||
|
|
||||||
|
The too frequent use of *but* as a conjunction leads to the fault discussed under Rule 14. A loose sentence formed with *but* can always be converted into a periodic sentence formed with *although*, as illustrated under Rule 4.
|
||||||
|
|
||||||
|
Particularly awkward is the following of one *but* by another, making a contrast to a contrast or a reservation to a reservation. This is easily corrected by re-arrangement.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| America had vast resources, but she seemed almost wholly unprepared for war. But within a year she had created an army of four million men. | America seemed almost wholly unprepared for war, but she had vast resources. Within a year she had created an army of four million men. |
|
||||||
|
|
||||||
|
**Can.** Means *am (is, are) able*. Not to be used as a substitute for *may*.
|
||||||
|
|
||||||
|
**Case.** The Concise Oxford Dictionary begins its definition of this word: “instance of a thing's occurring; usual state of affairs.” In these two senses, the word is usually unnecessary.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| In many cases, the rooms were poorly ventilated. | Many of the rooms were poorly ventilated. |
|
||||||
|
| It has rarely been the case that any mistake has been made. | Few mistakes have been made. |
|
||||||
|
|
||||||
|
See Wood, Suggestions to Authors, pp. 68–71, and Quiller-Couch, The Art of Writing, pp. 103–106.
|
||||||
|
|
||||||
|
**Certainly.** Used indiscriminately by some writers, much as others use *very*, to intensify any and every statement. A mannerism of this kind, bad in speech, is even worse in writing.
|
||||||
|
|
||||||
|
**Character.** Often simply redundant, used from a mere habit of wordiness.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Acts of a hostile character | Hostile acts |
|
||||||
|
|
||||||
|
**Claim, vb.** With object-noun, means *lay claim to*. May be used with a dependent clause if this sense is clearly involved: “He claimed that he was the sole surviving heir.” (But even here, “claimed to be” would be better.) Not to be used as a substitute for *declare*, *maintain*, or *charge*.
|
||||||
|
|
||||||
|
**Clever.** This word has been greatly overused; it is best restricted to ingenuity displayed in small matters.
|
||||||
|
|
||||||
|
**Compare.** To *compare to* is to point out or imply resemblances, between objects regarded as essentially of different order; to *compare with* is mainly to point out differences, between objects regarded as essentially of the same order. Thus life has been compared to a pilgrimage, to a drama, to a battle; Congress may be compared with the British Parliament. Paris has been compared to ancient Athens; it may be compared with modern London.
|
||||||
|
|
||||||
|
**Consider.** Not followed by *as* when it means “believe to be.” “I consider him thoroughly competent.” Compare, “The lecturer considered Cromwell first as soldier and second as administrator,” where “considered” means “examined” or “discussed.”
|
||||||
|
|
||||||
|
**Data.** A plural, like *phenomena* and *strata*.
|
||||||
|
|
||||||
|
These data were tabulated.
|
||||||
|
|
||||||
|
**Dependable.** A needless substitute for *reliable*, *trustworthy*.
|
||||||
|
|
||||||
|
**Different than.** Not permissible. Substitute *different from*, *other than*, or *unlike*.
|
||||||
|
|
||||||
|
**Divided into.** Not to be misused for *composed of*. The line is sometimes difficult to draw; doubtless plays are divided into acts, but poems are composed of stanzas.
|
||||||
|
|
||||||
|
**Don't.** Contraction of *do not*. The contraction of *does not* is *doesn't*.
|
||||||
|
|
||||||
|
**Due to.** Incorrectly used for *through*, *because of*, or *owing to*, in adverbial phrases: “He lost the first game, due to carelessness.” In correct use related as predicate or as modifier to a particular noun: “This invention is due to Edison;” “losses due to preventable fires.”
|
||||||
|
|
||||||
|
**Folk.** A collective noun, equivalent to *people*. Use the singular form only.
|
||||||
|
|
||||||
|
**Effect.** As noun, means *result*; as verb, means *_to_ bring about*, *accomplish* (not to be confused with *affect*, which means “to influence”).
|
||||||
|
|
||||||
|
As noun, often loosely used in perfunctory writing about fashions, music, painting, and other arts: “an Oriental effect;” “effects in pale green;” “very delicate effects;” “broad effects;” “subtle effects;” “a charming effect was produced by.” The writer who has a definite meaning to express will not take refuge in such vagueness.
|
||||||
|
|
||||||
|
**Etc.** Equivalent to *and the rest*, *and so forth*, and hence not to be used if one of these would be insufficient, that is, if the reader would be left in doubt as to any important particulars. Least open to objection when it represents the last terms of a list already given in full, or immaterial words at the end of a quotation.
|
||||||
|
|
||||||
|
At the end of a list introduced by *such as*, *for example*, or any similar expression, *etc.* is incorrect.
|
||||||
|
|
||||||
|
**Fact.** Use this word only of matters of a kind capable of direct verification, not of matters of judgment. That a particular event happened on a given date, that lead melts at a certain temperature, are facts. But such conclusions as that Napoleon was the greatest of modern generals, or that the climate of California is delightful, however incontestable they _may be_, are not properly facts.
|
||||||
|
|
||||||
|
On the formula *the fact that*, see under Rule 13.
|
||||||
|
|
||||||
|
**Factor.** A hackneyed word; the expressions of which it forms part can usually be replaced by something more direct and idiomatic.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| His superior training was the great factor in his winning the match. | He won the match by being better trained. |
|
||||||
|
| Heavy artillery has become an increasingly important factor in deciding battles. | Heavy artillery has played a constantly larger part in deciding battles. |
|
||||||
|
|
||||||
|
**Feature.** Another hackneyed word; like *factor* it usually adds nothing to the sentence in which it occurs.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A feature of the entertainment especially worthy of mention was the singing of Miss A. | (Better use the same number of words to tell what Miss A. sang, or if the programme has already been given, to tell how she sang.) |
|
||||||
|
|
||||||
|
As a verb, in the advertising sense of *offer as a special attraction*, to be avoided.
|
||||||
|
|
||||||
|
**Fix.** Colloquial in America for *arrange*, *prepare*, *mend*. In writing restrict it to its literary senses, *fasten*, *make firm or immovable*, etc.
|
||||||
|
|
||||||
|
**Get.** The colloquial *have got* for *have* should not be used in writing. The preferable form of the participle is *got*.
|
||||||
|
|
||||||
|
**He is a man who.** A common type of redundant expression; see Rule 13.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| He is a man who is very ambitious. | He is very ambitious. |
|
||||||
|
| Spain is a country which I have always wanted to visit. | I have always wanted to visit Spain. |
|
||||||
|
|
||||||
|
**Help.** See under **But**.
|
||||||
|
|
||||||
|
**However.** In the meaning *nevertheless*, not to come first in its sentence or clause.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| The roads were almost impassable. However, we at last succeeded in reaching camp. | The roads were almost impassable. At last, however, we succeeded in reaching camp. |
|
||||||
|
|
||||||
|
When *however* comes first, it means *in whatever way* or *to whatever extent*.
|
||||||
|
|
||||||
|
However you advise him, he will probably do as he thinks best.
|
||||||
|
|
||||||
|
However discouraging the prospect, he never lost heart.
|
||||||
|
|
||||||
|
**Interesting.** Avoid this word as a perfunctory means of introduction. Instead of announcing that what you are about to tell is interesting, make it so.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| An interesting story is told of | (Tell the story without preamble.) |
|
||||||
|
| In connection with the anticipated visit of Mr. B. to America, it is interesting to recall that he | Mr. B., who it is expected will soon visit America |
|
||||||
|
|
||||||
|
**Kind of.** Not to be used as a substitute for *rather* (before adjectives and verbs), or except in familiar style, for *something like* (before nouns). Restrict it to its literal sense: “Amber is a kind of fossil resin;” “I dislike that kind of notoriety.” The same holds true of *sort of*.
|
||||||
|
|
||||||
|
**Less.** Should not be misused for *fewer*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| He had less men than in the previous campaign | He had fewer men than in the previous campaign |
|
||||||
|
|
||||||
|
*Less* refers to quantity, *fewer* to number. “His troubles are less than mine” means “His troubles are not so great as mine.” “His troubles are fewer than mine” means “His troubles are not so numerous as mine.” It is, however, correct to say, “The signers of the petition were less than a hundred,” where the round number *a hundred* is something like a collective noun, and *less* is thought of as meaning a less quantity or amount.
|
||||||
|
|
||||||
|
**Like.** Not to be misused for *as*. *Like* governs nouns and pronouns; before phrases and clauses the equivalent word is *as*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| We spent the evening like in the old days. | We spent the evening as in the old days. |
|
||||||
|
| He thought like I did. | He thought as I did (like me). |
|
||||||
|
|
||||||
|
**Line, along these lines.** *Line* in the sense of *course of procedure*, *conduct*, *thought*, is allowable, but has been so much overworked, particularly in the phrase *along these lines*, that a writer who aims at freshness or originality had better discard it entirely.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Mr. B. also spoke along the same lines. | Mr. B. also spoke, to the same effect. |
|
||||||
|
| He is studying along the line of French literature. | He is studying French literature. |
|
||||||
|
|
||||||
|
**Literal, literally.** Often incorrectly used in support of exaggeration or violent metaphor.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A literal flood of abuse. | A flood of abuse. |
|
||||||
|
| Literally dead with fatigue | Almost dead with fatigue (dead tired) |
|
||||||
|
|
||||||
|
**Lose out.** Meant to be more emphatic than *lose*, but actually less so, because of its commonness. The same holds true of *try out*, *win out*, *sign up*, *register up*. With a number of verbs, *out* and *up* form idiomatic combinations: *find out*, *run out*, *turn out*, *cheer up*, *dry up*, *make up*, and others, each distinguishable in meaning from the simple verb. *Lose out* is not.
|
||||||
|
|
||||||
|
**Most.** Not to be used for *almost*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Most everybody | Almost everybody |
|
||||||
|
| Most all the time | Almost all the time |
|
||||||
|
|
||||||
|
**Nature.** Often simply redundant, used like *character*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Acts of a hostile _nature_ | Hostile acts |
|
||||||
|
|
||||||
|
Often vaguely used in such expressions as a “lover of nature;” “poems about nature.” Unless more specific statements follow, the reader cannot tell whether the poems have to do with natural scenery, rural life, the sunset, the untracked wilderness, or the habits of squirrels.
|
||||||
|
|
||||||
|
**Near by.** Adverbial phrase, not yet fully accepted as good English, though the analogy of *close by* and *hard by* seems to justify it. *Near*, or *near at hand*, is as good, if not better.
|
||||||
|
|
||||||
|
Not to be used as an adjective; use *neighboring*.
|
||||||
|
|
||||||
|
**Oftentimes, ofttimes.** Archaic forms, no longer in good use. The modern word is *often*.
|
||||||
|
|
||||||
|
**One hundred and one.** Retain the *and* in this and similar expressions, in accordance with the unvarying usage of English prose from Old English times.
|
||||||
|
|
||||||
|
**One of the most.** Avoid beginning essays or paragraphs with this formula, as, “One of the most interesting developments of modern science is, etc.;” “Switzerland is one of the most interesting countries of Europe.” There is nothing wrong in this; it is simply threadbare and forcible-feeble.
|
||||||
|
|
||||||
|
A common blunder is to use a singular verb in a relative clause following this or a similar expression, when the relative is the subject.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| One of the ablest men that has attacked this problem. | One of the ablest men that have attacked this problem. |
|
||||||
|
|
||||||
|
**Participle for verbal noun.**
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Do you mind me asking a question? | Do you mind my asking a question? |
|
||||||
|
| There was little prospect of the Senate accepting even this compromise. | There was little prospect of the Senate's accepting even this compromise. |
|
||||||
|
|
||||||
|
In the left-hand column, *asking* and *accepting* are present participles; in the right-hand column, they are verbal nouns (gerunds). The construction shown in the left-hand column is occasionally found, and has its defenders. Yet it is easy to see that the second sentence has to do not with a prospect of the Senate, but with a prospect of accepting. In this example, at least, the construction is plainly illogical.
|
||||||
|
|
||||||
|
As the authors of The King's English point out, there are sentences apparently, but not really, of this type, in which the possessive is not called for.
|
||||||
|
|
||||||
|
I cannot imagine Lincoln refusing his assent to this measure.
|
||||||
|
|
||||||
|
In this sentence, what the writer cannot imagine is Lincoln himself, in the act of refusing his assent. Yet the meaning would be virtually the same, except for a slight loss of vividness, if he had written,
|
||||||
|
|
||||||
|
I cannot imagine Lincoln's refusing his assent to this measure.
|
||||||
|
|
||||||
|
By using the possessive, the writer will always be on the safe side.
|
||||||
|
|
||||||
|
In the examples above, the subject of the action is a single, unmodified term, immediately preceding the verbal noun, and the construction is as good as any that could be used. But in any sentence in which it is a mere clumsy substitute for something simpler, or in which the use of the possessive is awkward or impossible, should of course be recast.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| In the event of a reconsideration of the whole matter's becoming necessary | If it should become necessary to reconsider the whole matter |
|
||||||
|
| There was great dissatisfaction with the decision of the arbitrators being favorable to the company. | There was great dissatisfaction that the arbitrators should have decided in favor of the company. |
|
||||||
|
|
||||||
|
**People.** *The people* is a political term, not to be confused with *the public*. From the people comes political support or opposition; from the public comes artistic appreciation or commercial patronage.
|
||||||
|
|
||||||
|
**Phase.** Means a stage of transition or development: “the phases of the moon;” “the last phase.” Not to be used for *aspect* or *topic*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Another phase of the subject | Another point (another question) |
|
||||||
|
|
||||||
|
**Possess.** Not to be used as a mere substitute for *have* or *own*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| He possessed great courage. | He had great courage (was very brave). |
|
||||||
|
| He was the fortunate possessor of | He owned |
|
||||||
|
|
||||||
|
**Prove.** The past participle is *proved*.
|
||||||
|
|
||||||
|
**Respective, respectively.** These words may usually be omitted with advantage.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Works of fiction are listed under the names of their respective authors. | Works of fiction are listed under the names of their authors. |
|
||||||
|
| The one mile and two mile runs were won by Jones and Cummings respectively. | The one mile and two mile runs were won by Jones and by Cummings. |
|
||||||
|
|
||||||
|
In some kinds of formal writing, as geometrical proofs, it may be necessary to use *respectively*, but it should not appear in writing on ordinary subjects.
|
||||||
|
|
||||||
|
**Shall, Will.** The future tense requires *shall* for the first person, *will* for the second and third. The formula to express the speaker's belief regarding his future action or state is *I shall*; *I will* expresses his determination or his consent.
|
||||||
|
|
||||||
|
**Should.** See under **Would**.
|
||||||
|
|
||||||
|
**So.** Avoid, in writing, the use of *so* as an intensifier: “so good;” “so warm;” “so delightful.”
|
||||||
|
|
||||||
|
On the use of *so* to introduce clauses, see Rule 4.
|
||||||
|
|
||||||
|
**Sort of.** See under **Kind of**.
|
||||||
|
|
||||||
|
**Split Infinitive.** There is precedent from the fourteenth century downward for interposing an adverb between *to* and the infinitive which it governs, but the construction is in disfavor and is avoided by nearly all careful writers.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| To diligently inquire | To inquire diligently |
|
||||||
|
|
||||||
|
**State.** Not to be used as a mere substitute for *say*, *remark*. Restrict it to the sense of *express fully or clearly*, as, “He refused to state his objections.”
|
||||||
|
|
||||||
|
**Student Body.** A needless and awkward expression meaning no more than the simple word *students*.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| A member of the student body | A student |
|
||||||
|
| Popular with the student body | Liked by the students |
|
||||||
|
| The student body passed resolutions. | The students passed resolutions. |
|
||||||
|
|
||||||
|
**System.** Frequently used without need.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Dayton has adopted the commission system of _government._ | Dayton has adopted government by commission. |
|
||||||
|
| The dormitory system | Dormitories |
|
||||||
|
|
||||||
|
**Thanking You in Advance.** This sounds as if the writer meant, “It will not be worth my while to write to you again.” In making your request, write, “Will you please,” or “I shall be obliged,” and if anything further seems necessary write a letter of acknowledgment later.
|
||||||
|
|
||||||
|
**They.** A common inaccuracy is the use of the plural pronoun when the antecedent is a distributive expression such as *each*, *each one*, *everybody*, *every one*, *many a man*, which, though implying more than one person, requires the pronoun to be in the singular. Similar to this, but with even less justification, is the use of the plural pronoun with the antecedent *anybody*, *any one*, *somebody*, *some one*, the intention being either to avoid the awkward “he or she,” or to avoid committing oneself to either. Some bashful speakers even say, “A friend of mine told me that they, etc.”
|
||||||
|
|
||||||
|
Use *he* with all the above words, unless the antecedent is or must be feminine.
|
||||||
|
|
||||||
|
**Very.** Use this word sparingly. Where emphasis is necessary, use words strong in themselves.
|
||||||
|
|
||||||
|
**Viewpoint.** Write *point of view*, but do not misuse this, as many do, for *view* or *opinion*.
|
||||||
|
|
||||||
|
**While.** Avoid the indiscriminate use of this word for *and*, *but*, and *although*. Many writers use it frequently as a substitute for *and* or *but*, either from a mere desire to vary the connective, or from uncertainty which of the two connectives is the more appropriate. In this use it is best replaced by a semicolon.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| The office and salesrooms are on the ground floor, while the rest of the building is devoted to manufacturing. | The office and salesrooms are on the ground floor; the rest of the building is devoted to manufacturing. |
|
||||||
|
|
||||||
|
Its use as a virtual equivalent of *although* is allowable in sentences where this leads to no ambiguity or absurdity.
|
||||||
|
|
||||||
|
While I admire his energy, I wish it were employed in a better cause.
|
||||||
|
|
||||||
|
This is entirely correct, as shown by the paraphrase,
|
||||||
|
|
||||||
|
I admire his energy; at the same time I wish it were employed in a better cause.
|
||||||
|
|
||||||
|
Compare:
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| While the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. | Although the temperature reaches 90 or 95 degrees in the daytime, the nights are often chilly. |
|
||||||
|
|
||||||
|
The paraphrase,
|
||||||
|
|
||||||
|
The temperature reaches 90 or 95 degrees in the daytime; at the same time the nights are often chilly,
|
||||||
|
|
||||||
|
shows why the use of *while* is incorrect.
|
||||||
|
|
||||||
|
In general, the writer will do well to use *while* only with strict literalness, in the sense of *during the time that*.
|
||||||
|
|
||||||
|
**Whom.** Often incorrectly used for *who* before *he said* or similar expressions, when it is really the subject of a following verb.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| His brother, whom he said would send him the money | His brother, who he said would send him the money |
|
||||||
|
| The man whom he thought was his friend | The man who (that) he thought was his friend (whom he thought his friend) |
|
||||||
|
|
||||||
|
**Worth while.** Overworked as a term of vague approval and (with *not*) of disapproval. Strictly applicable only to actions: “Is it worth while to telegraph?”
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| His books are not worth while. | His books are not worth reading (are not worth one's while to read; do not repay reading; are worthless). |
|
||||||
|
|
||||||
|
The use of *worth while* before a noun (“a worth while story”) is indefensible.
|
||||||
|
|
||||||
|
**Would.** A conditional statement in the first person requires *should*, not *would*.
|
||||||
|
|
||||||
|
I should not have succeeded without his help.
|
||||||
|
|
||||||
|
The equivalent of *shall* in indirect quotation after a verb in the past tense is *should*, not *would*.
|
||||||
|
|
||||||
|
He predicted that before long we should have a great surprise.
|
||||||
|
|
||||||
|
To express habitual or repeated action, the past tense, without *would*, is usually sufficient, and from its brevity, more emphatic.
|
||||||
|
|
||||||
|
| Original | Revision |
|
||||||
|
| --- | --- |
|
||||||
|
| Once a year he would visit the old mansion. | Once a year he visited the old mansion. |
|
||||||
@@ -0,0 +1,901 @@
|
|||||||
|
# Signs of AI Writing
|
||||||
|
|
||||||
|
[![A screenshot of ChatGPT reading: "[header] Legacy & Interpretation [body] The "Black Hole Edition" is not just a meme — it's a celebration of grassroots car culture, where ideas are limitless and fun is more important than spec sheets. Whether powered by a rotary engine, a V8 swap, or an imagined fighter jet turbine, the Miata remains the canvas for car enthusiasts worldwide."](https://upload.wikimedia.org/wikipedia/commons/thumb/5/59/ChatGPT_response_screenshot_1.jpg/250px-ChatGPT_response_screenshot_1.jpg)](https://en.wikipedia.org/wiki/File:ChatGPT_response_screenshot_1.jpg)
|
||||||
|
|
||||||
|
*LLMs tend to have an identifiable writing style.*
|
||||||
|
|
||||||
|
This is a list of writing and formatting conventions typical of [AI chatbots](https://en.wikipedia.org/wiki/AI_chatbot "AI chatbot") such as [ChatGPT](https://en.wikipedia.org/wiki/ChatGPT "ChatGPT"), with real examples taken from Wikipedia articles and drafts. It is a [field guide](https://en.wikipedia.org/wiki/Field_guide "Field guide") to help detect [undisclosed AI-generated content](https://en.wikipedia.org/wiki/Wikipedia:LLMDISCLOSE "Wikipedia:LLMDISCLOSE") on Wikipedia. This list is *descriptive*, not *prescriptive*; it consists of observations, not rules. Advice about formatting or language to avoid in Wikipedia articles can be found in the [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PAG "Wikipedia:PAG") and the [Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:MOS "Wikipedia:MOS"), but does not belong on this page.
|
||||||
|
|
||||||
|
This list is *not* a ban on certain words, phrases, or punctuation. Not all text featuring these indicators is AI-generated, as the [large language models](https://en.wikipedia.org/wiki/Large_language_model "Large language model") that power AI chatbots are trained on human writing, including the writing of Wikipedia editors. This is simply a catalog of very common patterns observed over many thousands of instances of AI-generated text, *specific to Wikipedia.* While some of its advice may be broadly applicable, some signs—particularly those involving punctuation and formatting—may not apply in a non-Wikipedia context.
|
||||||
|
|
||||||
|
The patterns here are also only potential *signs* of a problem, not *the problem itself*. While many of these issues are immediately obvious and easy to fix—e.g., excessive boldface, poor use of language and punctuation, broken markup, citation style quirks—they can point to less outwardly visible problems that carry [much more serious policy risks](https://en.wikipedia.org/wiki/Wikipedia:AIFAIL "Wikipedia:AIFAIL"). If LLM-generated text is polished enough (initially or subsequently), those surface defects might not be present, but deeper problems can be. Please do not merely treat these signs as the problems to be fixed; that could just make detection harder. The actual problems are those deeper concerns, so make sure to address them, either yourself or by flagging them, per the advice at [Wikipedia:Large language models §Handling suspected LLM-generated content](https://en.wikipedia.org/wiki/Wikipedia:Large_language_models#Handling_suspected_LLM-generated_content "Wikipedia:Large language models") and [Wikipedia:WikiProject AI Cleanup/Guide](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup/Guide "Wikipedia:WikiProject AI Cleanup/Guide").
|
||||||
|
|
||||||
|
The [speedy deletion policy](https://en.wikipedia.org/wiki/Wikipedia:Speedy_deletion "Wikipedia:Speedy deletion") criterion [G15](https://en.wikipedia.org/wiki/Wikipedia:G15 "Wikipedia:G15") (LLM-generated pages without human review) is limited to the most objective and least contestable indications that the page's content was generated by an LLM. There are three such indicators, the first of which can be found in [§Communication intended for the user](#communication-intended-for-the-user) and the other two in [§Citations](#citations).
|
||||||
|
|
||||||
|
Do not solely rely on [artificial intelligence content detection](https://en.wikipedia.org/wiki/Artificial_intelligence_content_detection "Artificial intelligence content detection") tools (such as [GPTZero](https://en.wikipedia.org/wiki/GPTZero "GPTZero")) to evaluate whether text is LLM-generated. While they perform better than might be achieved by chance, these tools have non-trivial error rates and cannot replace human judgment.[^1] Detectors can be brittle to multiple factors such as text modifications (e.g. paraphrasing and spacing changes) and the use of generative models not seen during detector training.[^2] By the same token, do not trust too much in your own interpretation. Research shows that people who use LLMs heavily themselves can correctly determine whether an article was generated by AI about 90% of the time, which means that if you are an expert user of LLMs and you tag 10 pages as being AI-generated, you've probably falsely accused one editor.[^3] People who don't personally use LLMs much do only slightly better than random chance (in both directions) for identifying AI-generated articles.[^3]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Regression to the Mean
|
||||||
|
|
||||||
|
LLMs (and [artificial neural networks](https://en.wikipedia.org/wiki/Artificial_neural_network "Artificial neural network") in general) use statistical algorithms to guess (infer) what should come next based on a large corpus of training material. It thus tends to [regress to the mean](https://en.wikipedia.org/wiki/Regression_to_the_mean "Regression to the mean"); that is, the result tends toward the most statistically likely result that applies to the widest variety of cases. It can simultaneously be a strength and a "tell" for detecting AI-generated content.
|
||||||
|
|
||||||
|
For example, LLMs are usually trained on data from the internet in which famous people are generally described with positive, important-sounding language. Consequently, the LLM tends to omit specific, unusual, nuanced facts (which are statistically rare) and replace them with more generic, positive descriptions (which are statistically common). Thus the highly specific "inventor of the first train-coupling device" might become "a revolutionary titan of industry." It is like shouting louder and louder that a portrait shows a uniquely important person, while the portrait itself is fading from a sharp photograph into a blurry, generic sketch. The subject becomes simultaneously less specific and more exaggerated.[^4]
|
||||||
|
|
||||||
|
This statistical regression to the mean, a smoothing over of specific facts into generic statements, that could equally apply to many topics, makes AI-generated content easier to detect.
|
||||||
|
|
||||||
|
### Undue emphasis on symbolism, legacy, and importance
|
||||||
|
|
||||||
|
**Words to watch:** *stands/serves as*, *is a testament/reminder*, *plays a vital/significant/crucial/pivotal role*, *underscores/highlights its importance/significance*, *reflects broader*, *symbolizing its ongoing/enduring/lasting impact*, *key turning point*, *indelible mark*, *deeply rooted*, *profound heritage*, *steadfast dedication*...
|
||||||
|
|
||||||
|
LLM writing often puffs up the importance of the subject matter by adding statements about how arbitrary aspects of the topic represent or contribute to a broader topic.[^5] There is a distinct and easily identifiable repertoire of ways that it writes these statements.[^6]
|
||||||
|
|
||||||
|
> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. [...]
|
||||||
|
>
|
||||||
|
> The founding of Idescat represented a significant shift toward regional statistical independence, enabling [Catalonia](https://en.wikipedia.org/wiki/Catalonia "Catalonia") to develop a statistical system tailored to its unique socio-economic context. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
|
||||||
|
|
||||||
|
> Kumba has long been an important center for trade and agriculture. [...] The establishment of road networks connecting Kumba to other parts of the Southwest Region, such as Mamfe and Buea, helped solidify its role as a regional hub.
|
||||||
|
|
||||||
|
LLMs may include these statements for even the most mundane of subjects like etymology or population data. Sometimes, they add hedging preambles acknowledging that the subject is relatively unimportant or low-profile, before talking about its importance anyway.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> During the [Spanish colonial period](https://en.wikipedia.org/wiki/Spanish_Colonial_Period_(Philippines) "Spanish Colonial Period (Philippines)"), the name *Bakunutan* was hispanized to *Bacnotan*, a modification reflected in official documents preserved in the [National Archives](https://en.wikipedia.org/wiki/National_Archives_of_the_Philippines "National Archives of the Philippines") in Manila. This etymology highlights the enduring legacy of the community's resistance and the transformative power of unity in shaping its identity.
|
||||||
|
|
||||||
|
> Though it saw only limited application, it contributes to the broader history of early aviation engineering and reflects the influence of French rotary designs on German manufacturers.
|
||||||
|
|
||||||
|
When talking about biology (e.g., when asked to discuss an animal or plant species), LLMs tend to over-emphasize connections to the broader ecosystem or environment, even when those connections are tenuous or generic. LLMs also tend to belabor the species' conservation status and research and preservation efforts, even if the status is unknown and no serious efforts exist.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> It plays a role in the ecosystem and contributes to Hawaii's rich cultural heritage. [...] Preserving this endemic species is vital not only for ecological diversity but also for sustaining the cultural traditions connected to Hawaii's native flora.
|
||||||
|
|
||||||
|
> Currently, there is no specific conservation assessment for *Lethrinops lethrinus* by the International Union for Conservation of Nature (IUCN). However, the general health of the Lake Malawi ecosystem is crucial for the survival of this and other endemic species. Factors such as overfishing, pollution, and habitat destruction could potentially impact their populations.
|
||||||
|
|
||||||
|
### Undue emphasis on notability, attribution, and media coverage
|
||||||
|
|
||||||
|
**Words to watch:** *independent coverage*, *local/regional/national/[country name] media outlets*, *music/business/tech outlets*, *active social media presence*
|
||||||
|
|
||||||
|
Similarly, LLMs act as if the best way to prove that a subject is notable is to hit readers over the head with claims of notability, often by listing sources that a subject has been covered in. They may or may not provide additional context as to what those sources have actually said about the subject, and often inaccurately attribute their own [superficial analyses](#superficial-analyses) to the source. This is more common in text from newer AI tools (2025 or later).
|
||||||
|
|
||||||
|
Human-written press releases have of course also cited news clippings for decades, but LLMs specifically asked to write a Wikipedia article often echo the exact wording of [Wikipedia's guidelines](https://en.wikipedia.org/wiki/Wikipedia:N "Wikipedia:N"), such as "independent coverage."
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> She spoke about AI on CNN, and was featured in Vogue, Wired, Toronto Star, and other media. [...] Her insights have also been featured in *Wired*, *Refinery29*, and other prominent media outlets.
|
||||||
|
|
||||||
|
> Her views have been cited in *The New York Times*, *BBC*, *Financial Times*, and *The Hindu*.
|
||||||
|
|
||||||
|
> Its significance is documented in archived school event programs and regional press coverage, including the *Mesabi Daily News*, which regularly reviewed performances held there.
|
||||||
|
|
||||||
|
On Wikipedia specifically, LLMs often painstakingly emphasize their sources in the body text—even for trivial coverage, uncontroversial facts, or other situations where a human Wikipedia editor would be more likely to either provide an inline citation or no source at all.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> The restaurant has also been mentioned in [ABC News](https://en.wikipedia.org/wiki/ABC_News_(Australia) "ABC News (Australia)") coverage relating to incidents in the surrounding precinct, underscoring its role as a well-known late-night venue in the city [of [Adelaide](https://en.wikipedia.org/wiki/Adelaide "Adelaide")].
|
||||||
|
|
||||||
|
> In the United States, university-based incubators and accelerators have expanded alongside these centers; an official Library of Congress review found that 31.5% of SBA [[Small Business Administration](https://en.wikipedia.org/wiki/Small_Business_Administration "Small Business Administration")] Growth Accelerator Fund Competition winners from 2014–2016 were university-based programs.
|
||||||
|
|
||||||
|
In articles about people/entities who use social media, LLMs will often note that they "maintain an active social media presence" or something similar. This wording is particularly idiosyncratic to AI text and relatively uncommon on Wikipedia before ~2024.
|
||||||
|
|
||||||
|
> The mall maintains a strong digital presence, particularly on Instagram, where it actively shares the latest updates and events. Forum Kochi has consistently demonstrated excellence in digital promotions, with high-quality, engaging, and impactful video content playing a key role in its outreach.
|
||||||
|
|
||||||
|
### Superficial analyses
|
||||||
|
|
||||||
|
**Words to watch:** *ensuring ...*, *highlighting ...*, *emphasizing ...*, *reflecting ...*, *underscoring ...*, *showcasing ...*, *aligns with...*, *contributing to...*
|
||||||
|
|
||||||
|
AI chatbots tend to insert superficial analysis of information, often in relation to its significance, recognition, or impact.[^7] This is often done by attaching a [present participle](https://en.wikipedia.org/wiki/Participle#Forms "Participle") ("-ing") phrase at the end of sentences, sometimes with [vague attributions](#vague-attributions-of-opinion) to third parties (see below).[^7][^5]
|
||||||
|
|
||||||
|
While [many of these words are strong AI tells on their own](https://en.wikipedia.org/wiki/Wikipedia:AIWORDS "Wikipedia:AIWORDS"),[^6][^8] an even stronger tell is when the subjects of these verbs are facts, events, or other inanimate things. A person, for example, can highlight or emphasize something, but a fact or event cannot. The "highlighting" or "underscoring" is not something that is actually happening; it is a claim by a disembodied narrator about what something means.[^5]
|
||||||
|
|
||||||
|
Such comments are usually [synthesis](https://en.wikipedia.org/wiki/Wikipedia:SYNTH "Wikipedia:SYNTH") and/or unattributed opinions in wikivoice. Newer chatbots with [retrieval-augmented generation](https://en.wikipedia.org/wiki/Retrieval-augmented_generation "Retrieval-augmented generation") (for example, an AI chatbot that can search the web) may attach these statements to [named sources](#undue-emphasis-on-notability-attribution-and-media-coverage)—e.g., "Roger Ebert highlighted the lasting influence"—regardless of whether those sources say anything close.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Douera enjoys close proximity to the capital city, Algiers, further enhancing its significance as a dynamic hub of activity and culture.
|
||||||
|
|
||||||
|
> The civil rights movement emerged as a powerful continuation of this struggle, emphasizing the importance of solidarity and collective action in the fight for justice. This historical legacy has influenced contemporary African-American families, shaping their values, community structures, and approaches to political engagement. Economically, the enduring impacts of systemic inequality have led to both challenges and innovations within African-American communities, driving a commitment to empowerment and social change that echoes through generations.
|
||||||
|
|
||||||
|
> Its bilingual monument sign, with inscriptions in both English and Spanish, underscores its role in bringing together Latter-day Saints from the United States and Mexico.
|
||||||
|
|
||||||
|
> These citations, spanning more than six decades and appearing in recognized academic publications, illustrate Blois' lasting influence in computational linguistics, grammar, and neology.
|
||||||
|
|
||||||
|
> It holds a pivotal place in the [East Central Railway Zone](https://en.wikipedia.org/wiki/East_Central_Railway_Zone "East Central Railway Zone") of [Indian Railways](https://en.wikipedia.org/wiki/Indian_Railways "Indian Railways"), serving as a major railway hub with historical significance. The station has [1,676 mm](https://en.wikipedia.org/wiki/5_ft_6_in_gauge_railway "5 ft 6 in gauge railway") (5 ft 6 in) [broad gauge](https://en.wikipedia.org/wiki/Broad_gauge "Broad gauge") along with 8 tracks and 6 platforms. [...] Historically, it has been crucial for linking [Darbhanga](https://en.wikipedia.org/wiki/Darbhanga "Darbhanga") with significant cities like [Delhi](https://en.wikipedia.org/wiki/Delhi "Delhi"), [Patna](https://en.wikipedia.org/wiki/Patna "Patna"), and [Kolkata](https://en.wikipedia.org/wiki/Kolkata "Kolkata"), facilitating the movement of passengers and goods. The station has supported various services, including passenger trains and express trains like the [Satyagrah Express](https://en.wikipedia.org/wiki/Satyagrah_Express "Satyagrah Express") and [Mithila Express](https://en.wikipedia.org/wiki/Mithila_Express "Mithila Express"), contributing to the socio-economic development of the region. [...] Over the years, Darbhanga Junction has seen several upgrades and modernization efforts aimed at improving facilities and operational efficiency, reflecting its continued relevance in the regional and national transportation landscape.
|
||||||
|
|
||||||
|
### Promotional and advertisement-like language
|
||||||
|
|
||||||
|
**Words to watch:** *continues to captivate*, *groundbreaking* (in the figurative sense), *stunning natural beauty*, *enduring/lasting legacy*, *nestled*, *in the heart of*, *boasts a*...
|
||||||
|
|
||||||
|
LLMs have serious problems keeping a neutral tone, especially when writing about something that could be considered "cultural heritage"—in which case they [constantly remind the reader of its importance](#undue-emphasis-on-symbolism-legacy-and-importance).
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and a significant place within the Amhara region. From its scenic landscapes to its historical landmarks, Alamata Raya Kobo offers visitors a fascinating glimpse into the diverse tapestry of Ethiopia. In this article, we will explore the unique characteristics that make Alamata Raya Kobo a town worth visiting and shed light on its significance within the Amhara region.
|
||||||
|
|
||||||
|
> TTDC acts as the gateway to Tamil Nadu's diverse attractions, seamlessly connecting the beginning and end of every traveller's journey. It offers dependable, value-driven experiences that showcase the state's rich history, spiritual heritage, and natural beauty.
|
||||||
|
|
||||||
|
In a similar way, LLM chatbots also add promotional/positive-sounding language to text about companies, business, and products, such that it sounds more like the transcript of a TV commercial.
|
||||||
|
|
||||||
|
> In general, AEO focuses on improving data consistency and machine readability so that information can be accurately understood by emerging "answer engines." Commonly discussed practices include using structured data formats such as [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD "JSON-LD") and [schema.org](https://en.wikipedia.org/wiki/Schema.org "Schema.org"), maintaining the freshness and accuracy of published information, and aligning digital entities with open web standards like [Wikidata](https://en.wikipedia.org/wiki/Wikidata "Wikidata") and Schema.org.
|
||||||
|
|
||||||
|
> The SOLLEI's exterior design communicates a powerful emotional presence, staying true to Cadillac's signature bold proportions. Its low, elongated silhouette is highlighted by a wide stance and an extended coupe door, which enhances accessibility to the spacious rear cabin. Smooth, uninterrupted surfaces and a pronounced A-line accentuate the vehicle's overall length, while a sleek, low tail imparts a sense of refined dynamism. A mid-body line runs seamlessly from the headlamps to the taillights, reinforcing the car's cohesive and elegant design. Traditional door handles have been replaced with discrete buttons, preserving the vehicle's clean and modern profile. In a nod to Cadillac's legacy of bold color choices, the exterior is finished in "Manila Cream"—a distinctive hue originally offered in 1957 and 1958. This heritage color has been thoughtfully revived and hand-painted by Cadillac artisans, showcasing the brand's dedication to craftsmanship and historical reverence.
|
||||||
|
|
||||||
|
### Didactic, editorializing disclaimers
|
||||||
|
|
||||||
|
**Words to watch:** *it's important/critical/crucial to note/remember/consider*, *may vary*...
|
||||||
|
|
||||||
|
LLMs often tell the reader about things "it's important to remember." This frequently takes the form of "disclaimers" to an imagined reader regarding safety or controversial topics, or disambiguating topics that vary in different locales/jurisdictions.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> The emergence of these informal groups reflects a growing recognition of the interconnected nature of urban issues and the potential for ANCs to play a role in shaping citywide policies. However, it's important to note that these caucuses operate outside the formal ANC structure and their influence on policy decisions may vary.
|
||||||
|
|
||||||
|
> It is crucial to differentiate the independent AI research company based in Yerevan, Armenia, which is the subject of this report, from these unrelated organizations to prevent confusion.
|
||||||
|
|
||||||
|
> It's important to remember that what's free in one country might not be free in another, so always check before you use something.
|
||||||
|
|
||||||
|
### Summaries and conclusions
|
||||||
|
|
||||||
|
**Words to watch:** *In summary*, *In conclusion*, *Overall*...
|
||||||
|
|
||||||
|
When generating longer outputs (such as when told to "write an article"), LLMs often add a section titled "Conclusion" or similar, and will often end a paragraph or section by summarizing and restating its core idea.[^9]
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> In summary, the educational and training trajectory for nurse scientists typically involves a progression from a master's degree in nursing to a Doctor of Philosophy in Nursing, followed by postdoctoral training in nursing research. This structured pathway ensures that nurse scientists acquire the necessary knowledge and skills to engage in rigorous research and contribute meaningfully to the advancement of nursing science.
|
||||||
|
|
||||||
|
### Outline-like conclusions about challenges and future prospects
|
||||||
|
|
||||||
|
**Words to watch:** *Despite its... faces several challenges...*, *Despite these challenges*, *Challenges and Legacy*, *Future Outlook*...
|
||||||
|
|
||||||
|
Many LLM-generated Wikipedia articles include a "Challenges" section, which typically begins with a sentence like "Despite its [positive/promotional words], [article subject] faces challenges..." and ends with either a vaguely positive assessment of the article subject,[^1] or speculation about how ongoing or potential initiatives could benefit the subject. Such paragraphs usually appear at the end of articles with a rigid outline structure, which may also include a separate section for "Future Prospects."
|
||||||
|
|
||||||
|
Note: This sign is about the rigid formula, not simply the mention of challenges or challenging.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Despite its industrial and residential prosperity, Korattur faces challenges typical of urban areas, including[...] With its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of the Ambattur industrial zone, embodying the synergy between industry and residential living.
|
||||||
|
|
||||||
|
> Despite its success, the Panama Canal faces challenges, including[...] Future investments in technology, such as automated navigation systems, and potential further expansions could enhance the canal's efficiency and maintain its relevance in global trade.
|
||||||
|
|
||||||
|
> Despite their promising applications, pyroelectric materials face several challenges that must be addressed for broader adoption. One key limitation is[...] Despite these challenges, the versatility of pyroelectric materials positions them as critical components for sustainable energy solutions and next-generation sensor technologies.
|
||||||
|
|
||||||
|
> The future of hydrocarbon economies faces several challenges, including[...] This section would speculate on potential developments and the changing landscape of global energy.
|
||||||
|
|
||||||
|
> Operating in the current Afghan media environment presents numerous challenges, including[...] Despite these challenges, Amu TV has managed to continue to provide a vital service to the Afghan population.
|
||||||
|
|
||||||
|
> For example, while the methodology supports transdisciplinary collaboration in principle, applying it effectively in large, heterogeneous teams can be challenging. [...] SCE continues to evolve in response to these challenges.
|
||||||
|
|
||||||
|
### Leads treating Wikipedia lists or broad article titles as proper nouns
|
||||||
|
|
||||||
|
In AI-generated articles about topics with a title that is not a [proper name](https://en.wikipedia.org/wiki/Proper_name "Proper name"), such as a [list](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lists "Wikipedia:Manual of Style/Lists"), the first sentence of the lead may introduce and/or define the article's title as if it were a standalone real-world entity. While the [MOS](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Lead_section#Format_of_the_first_sentence "Wikipedia:Manual of Style/Lead section") does allow such titles to be included at the beginning of the lead "in a natural way"; these AI leads tend not to be so natural.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> "The Effects of Foreign language anxiety on Learning" refers to the feelings of tension, nervousness, and apprehension experienced when learning or using a language other than one's native tongue.
|
||||||
|
|
||||||
|
> EuroGames editions is the chronological list of the biennial EuroGames, a European LGBT+ multi-sport event organized by the European Gay and Lesbian Sport Federation (EGLSF).
|
||||||
|
|
||||||
|
> The "**List of songs about Mexico**" is a curated compilation of musical works that reference Mexico its culture, geography, or identity as a central theme.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Language and Grammar
|
||||||
|
|
||||||
|
### Overused "AI vocabulary" words
|
||||||
|
|
||||||
|
**Words to watch:** *align/aligns/aligning with*,[^6][^8] *crucial*,[^1] *delve/delves/delving* (pre-2025),[^6][^8][^1] *emphasizing*,[^6][^8] *enduring*,[^8] *enhance/enhances/enhancing*,[^8][^1] *fostering*,[^8][^1] *garnered/garnering*,[^6][^8] *highlight/highlighted/highlighting/highlights* (as a verb),[^1] *interplay*,[^8] *intricate/intricacies*,[^6][^8][^7] *key* (as an adjective), *landscape*,[^8] *leveraging*,[^1] *multifaceted*,[^6][^8][^7] *notably*,[^8] *nuanced*,[^6][^8] *realm*,[^8] *robust*,[^1] *seamless/seamlessly*,[^1] *shed light on*, *showcasing*,[^8] *streamline*,[^1] *tapestry*,[^8] *testament*,[^1][^8] *underpin/underpins/underpinning*,[^8] *underscore/underscores/underscoring*,[^8] *vibrant*,[^8][^7] *vital*,[^1] ...
|
||||||
|
|
||||||
|
Many studies have demonstrated that LLMs overuse certain words – especially compared to pre-2022 text, which is almost certain to be human-written.[^6] These "AI vocabulary" words are also ubiquitous in AI-generated encyclopedias, such as [Grokipedia](https://en.wikipedia.org/wiki/Grokipedia "Grokipedia"), and in AI-generated Wikipedia text. They often co-occur in LLM output: where there is one, there are likely others.[^10] An edit introducing one or two of these words may not be a big deal, but an edit (post-2022) introducing lots of them, lots of times, is one of the strongest tells for AI use.
|
||||||
|
|
||||||
|
The distribution of "AI vocabulary" is slightly different depending on which chatbot or LLM was used,[^7] and has changed over time. For instance, the word *delve* was famously overused by ChatGPT until 2025, when its incidence dropped off sharply.[^11]
|
||||||
|
|
||||||
|
Please keep context in mind. For example, while the word "underscore" is overused in AI text, it can also refer to a literal underline mark, or to [incidental music](https://en.wikipedia.org/wiki/Incidental_music "Incidental music").
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Somali cuisine is an intricate and diverse fusion of a multitude of culinary influences, drawing from the rich tapestry of [Arab](https://en.wikipedia.org/wiki/Arab_cuisine "Arab cuisine"), [Indian](https://en.wikipedia.org/wiki/Indian_cuisine "Indian cuisine"), and [Italian](https://en.wikipedia.org/wiki/Italian_cuisine "Italian cuisine") flavours. This culinary tapestry is a direct result of Somalia's longstanding heritage of vibrant trade and bustling commerce. [...]
|
||||||
|
>
|
||||||
|
> Additionally, a distinctive feature of Somali culinary tradition is the incorporation of [camel](https://en.wikipedia.org/wiki/Camel "Camel") [meat](https://en.wikipedia.org/wiki/Meat "Meat") and [milk](https://en.wikipedia.org/wiki/Milk "Milk"). They are considered a delicacy and serve as cherished and fundamental elements in the rich tapestry of Somali cuisine. [...]
|
||||||
|
>
|
||||||
|
> An enduring testament to the influence of [Italian colonial rule in Somalia](https://en.wikipedia.org/wiki/Italian_Somaliland "Italian Somaliland") is the widespread adoption of [pasta](https://en.wikipedia.org/wiki/Pasta "Pasta") and [lasagne](https://en.wikipedia.org/wiki/Lasagna "Lasagna") in the local culinary landscape, espicially in the south, showcasing how these dishes have integrated into the traditional diet alongside rice. [...]
|
||||||
|
>
|
||||||
|
> Additionally, Somali merchants played a pivotal role in the global coffee trade, being one of the first to export coffee beans.
|
||||||
|
|
||||||
|
### Negative parallelisms
|
||||||
|
|
||||||
|
Parallel constructions involving "not", "but", or "however" such as "Not only ... but ..." or "It is not just about ..., it's ..." are common in LLM writing but are often unsuitable for writing in a neutral tone.[^1][^11]
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> **Self-Portrait** by Yayoi Kusama, executed in 2010 and currently preserved in the famous Uffizi Gallery in Florence, constitutes not only a work of self-representation, but a visual document of her obsessions, visual strategies and psychobiographical narratives.
|
||||||
|
|
||||||
|
> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere.
|
||||||
|
|
||||||
|
Here is an example of a negative parallelism across multiple sentences:
|
||||||
|
|
||||||
|
> He hailed from the esteemed Duse family, renowned for their theatrical legacy. Eugenio's life, however, took a path that intertwined both personal ambition and familial complexities.
|
||||||
|
|
||||||
|
### Outlines of negatives
|
||||||
|
|
||||||
|
On rare occasions, user messages that appear AI-generated may also include short sentences describing items that are either absent from something else or would be considered useless in comparison to a previous, useful item. Some of these may read something along the lines of "no ..., no ..., just ..." or "What matters is ..., not ..., not ...".
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> There are no long-form profiles. No editorial insights. No coverage of her game dev career. No notable accolades. Just TikTok recaps and callouts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> The process demands rigor — not emotional fatigue, not personal offense, and certainly not a premature exit masked as moral high ground.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> Not a career, not a body of work, not sustained relevance — just an algorithmic moment.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> This is not a close call. It is not a gray area. This page should be gone, fully, cleanly, and without delay. No redirect. No merge. Just delete.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> Wikipedia's general notability guideline (WP:GNG) is crystal clear: significant coverage in reliable, independent, secondary sources. Not a few throwaway articles echoing Twitter drama. Not reactionary posts exploiting culture war tension. Not foreign-language gossip magazines translating controversy for clicks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> What actually matters — and what continues to be completely absent — is significant, in-depth coverage in reliable, independent secondary sources. Not gossip sites. Not recycled outrage. Not tabloid blurbs about one viral controversy. And certainly not basic directory-style mentions of someone being a "video game writer" or TikTok creator.
|
||||||
|
|
||||||
|
### Rule of three
|
||||||
|
|
||||||
|
LLMs overuse the '[rule of three](https://en.wikipedia.org/wiki/Rule_of_three_(writing) "Rule of three (writing)")'. This can take different forms, from "adjective, adjective, adjective" to "short phrase, short phrase, and short phrase".[^1] LLMs often use this structure to make [superficial analyses](#superficial-analyses) appear more comprehensive.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> The Amaze Conference brings together global SEO professionals, marketing experts, and growth hackers to discuss the latest trends in digital marketing. The event features keynote sessions, panel discussions, and networking opportunities.
|
||||||
|
|
||||||
|
### Vague attributions of opinion
|
||||||
|
|
||||||
|
**Words to watch:** *Industry reports*, *Observers have cited*, *Some critics argue*...
|
||||||
|
|
||||||
|
AI chatbots tend to attribute opinions or claims to some vague authority—a practice called [weasel wording](https://en.wikipedia.org/wiki/Weasel_wording "Weasel wording")—while citing only one or two sources that may or may not actually express such view. They also tend to overgeneralize the perspective of one or few sources into that of a wider group.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> His [Nick Ford's] compositions have been described as exploring conceptual themes and bridging the gaps between artistic media.
|
||||||
|
|
||||||
|
— From [Draft:Nick Ford (musician)](https://en.wikipedia.org/wiki/Draft:Nick_Ford_(musician) "Draft:Nick Ford (musician)"). Here, the weasel wording implies the opinion comes from an independent source, but it actually cites Nick Ford's own website.
|
||||||
|
|
||||||
|
> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Efforts are ongoing to monitor its ecological health and preserve the surrounding grassland environment, which is part of a larger initiative to protect China's semi-arid ecosystems from degradation.
|
||||||
|
|
||||||
|
> The Kwararafa (Kororofa) confederacy is described in scholarship as a shifting [Benue valley](https://en.wikipedia.org/wiki/Benue_valley "Benue valley") coalition led by [Jukun](https://en.wikipedia.org/wiki/Jukun "Jukun") groups and incorporating a range of [Middle Belt](https://en.wikipedia.org/wiki/Middle_Belt "Middle Belt") peoples. Because much of the historical record derives from [Hausa](https://en.wikipedia.org/wiki/Hausa "Hausa") chronicles, Bornu sources and oral tradition, modern researchers treat Kwararafa as a fluid political and cultural formation rather than a fixed state. As a result, lists of member groups vary by period and source.
|
||||||
|
|
||||||
|
### Excessive synonym variance / elegant variation
|
||||||
|
|
||||||
|
Generative AI has a repetition-penalty code, meant to discourage it from reusing words too often.[^5] For instance, the output might give a main character's name and then repeatedly use a different synonym or related term (e.g., protagonist, key player, eponymous character) when mentioning it again.
|
||||||
|
|
||||||
|
Note: If a user adds multiple pieces of AI-generated content in separate edits, this tell may not apply, as each piece of text may have been generated in isolation.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Vierny, after a visit in Moscow in the early 1970's, committed to supporting artists resisting the constraints of socialist realism and discovered Yankilevskly, among others such as Ilya Kabakov and Erik Bulatov. In the challenging climate of Soviet artistic constraints, Yankilevsky, alongside other non-conformist artists, faced obstacles in expressing their creativity freely. Dina Vierny, recognizing the immense talent and the struggle these artists endured, played a pivotal role in aiding their artistic aspirations. [...]
|
||||||
|
>
|
||||||
|
> In this new chapter of his life, Yankilevsky found himself amidst a community of like-minded artists who, despite diverse styles, shared a common goal—to break free from the confines of state-imposed artistic norms, particularly socialist realism. [...]
|
||||||
|
>
|
||||||
|
> The move to Paris facilitated an environment where Yankilevsky could further explore and exhibit his distinctive artistic vision without the constraints imposed by the Soviet regime. Dina Vierny's unwavering support and commitment to the Russian avant-garde artists played a crucial role in fostering a space where their creativity could flourish, contributing to the rich tapestry of artistic expression in the vibrant cultural landscape of Paris. Vierny's commitment culminated in the groundbreaking exhibition "Russian Avant-Garde - Moscow 1973" at her Saint-Germain-des-Prés gallery, showcasing the diverse yet united front of non-conformist artists challenging the artistic norms of their time.
|
||||||
|
|
||||||
|
### False ranges
|
||||||
|
|
||||||
|
When *from ... to ...* constructions are not used figuratively, they are used to indicate the lower and upper bounds of a scale. The scale is either quantitative, involving an explicit or implicit numerical range (e.g. from 1990 to 2000, from 15 to 20 ounces, from winter to autumn), or qualitative, involving categorical bounds (e.g. "from seed to tree", "from mild to severe", "from white belt to black belt"). The same constructions may be used to form a [merism](https://en.wikipedia.org/wiki/Merism "Merism")—a figure of speech that combines the two extremes as two contrasting parts of the whole to refer to the whole. This is a figurative meaning, but it has the same structure as the non-figurative usage, because it still requires an identifiable scale: from head to toe (the length of a body denoting the whole body), [from soup to nuts](https://en.wiktionary.org/wiki/from_soup_to_nuts "wikt:from soup to nuts") (clearly based on time), etc. This is *not* a false range.
|
||||||
|
|
||||||
|
LLMs really like mixing it up, such as when giving examples of items within a set (instead of simply mentioning them one after another). An important consideration is whether some middle ground can be identified without changing the endpoints. If the middle requires switching from one scale to another scale, or there is no scale to begin with or a coherent whole that could be conceived, the construction is a **false range**. LLMs often employ "figurative" (often simply: meaningless) "from ... to ..." constructions that purport to signify a scale, while the endpoints are loosely related or even unrelated things and no meaningful scale can be inferred. LLMs do this because such meaningless language is used in persuasive writing to impress and woo, and LLMs are heavily influenced by examples of persuasive writing during their training.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars that forge the elements of life, to the enigmatic dance of dark matter and dark energy that shape its destiny.
|
||||||
|
>
|
||||||
|
> [...] Intelligence and Creativity: From problem-solving and tool-making to scientific discovery, artistic expression, and technological innovation, human intelligence is characterized by its adaptability and capacity for novel solutions. [...] Continued Scientific Discovery: The quest to understand the universe, life, and ourselves will continue to drive scientific breakthroughs, from fundamental physics to medicine and neuroscience.
|
||||||
|
|
||||||
|
### Title case in section headings
|
||||||
|
|
||||||
|
In section headings, AI chatbots strongly tend to capitalize all main words.[^1]
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Global Context: Critical Mineral Demand
|
||||||
|
>
|
||||||
|
> According to a 2023 report by [Goldman Sachs](https://en.wikipedia.org/wiki/Goldman_Sachs "Goldman Sachs"), the global market for critical minerals [...]
|
||||||
|
>
|
||||||
|
> Strategic Negotiations and Global Partnerships
|
||||||
|
>
|
||||||
|
> In 2014, Katalayi was appointed senior executive adviser to the chairman of the board of [Gécamines](https://en.wikipedia.org/wiki/G%C3%A9camines "Gécamines") [...]
|
||||||
|
>
|
||||||
|
> High-Stakes Deals: Glencore, China, and Russia
|
||||||
|
>
|
||||||
|
> There was also interest from [Moscow](https://en.wikipedia.org/wiki/Moscow "Moscow") for strategic Congolese assets. [...]
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Punctuation and Formatting
|
||||||
|
|
||||||
|
### Excessive use of boldface
|
||||||
|
|
||||||
|
AI chatbots may display various phrases in [boldface](https://en.wikipedia.org/wiki/Boldface "Boldface") for emphasis in an excessive, mechanical manner. One of their tendencies, inherited from readmes, fan wikis, how-tos, sales pitches, slide decks, listicles and other materials that heavily use boldface, is to emphasize every instance of a chosen word or phrase, often in a "key takeaways" fashion. Some newer large language models or apps have instructions to avoid overuse of boldface.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**. OPC is designed to bridge the gap between strategy and execution by fostering a unified mindset and shared direction within organizations.
|
||||||
|
|
||||||
|
> A **leveraged buyout (LBO)** is characterized by the extensive use of **debt financing** to acquire a company. This financing structure enables **private equity firms** and **financial sponsors** to control businesses while investing a relatively small portion of their own equity. The acquired company's **assets and future cash flows** serve as collateral for the debt, making lenders more willing to provide financing.
|
||||||
|
|
||||||
|
> **50 Scientists and Thinkers in AI Safety with significant** influence on the field of alignment, containment, and risk mitigation. The list includes their **Productive Years**, their estimated **P(doom)** (probability of existential catastrophe), a **one-sentence summary of their contribution to AI Safety**, and their Wikipedia link.
|
||||||
|
|
||||||
|
### Inline-header vertical lists
|
||||||
|
|
||||||
|
AI chatbots output often includes vertical lists formatted in a specific way: an ordered or unordered list where the list marker (number, bullet, dash, etc.) is followed by an inline boldfaced header, separated with a colon from the remaining descriptive text.
|
||||||
|
|
||||||
|
Instead of [proper wikitext](https://en.wikipedia.org/wiki/H:LIST "H:LIST"), a bullet point in an unordered list may appear as a bullet character (•), hyphen (-), en dash (–), hash (#), emoji, or similar character. Ordered lists (i.e. numbered lists) may use explicit numbers (such as `1.`) instead of standard wikitext. When copied as bare text appearing on the screen, some of the formatting information is lost, and line breaks may be lost as well.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> 1. Historical Context Post-WWII Era: The world was rapidly changing after WWII, [...] 2. Nuclear Arms Race: Following the U.S. atomic bombings, the Soviet Union detonated its first bomb in 1949, [...] 3. Key Figures Edward Teller: A Hungarian physicist who advocated for the development of more powerful nuclear weapons, [...] 4. Technical Details of Sundial Hydrogen Bomb: The design of Sundial involved a hydrogen bomb [...] 5. Destructive Potential: If detonated, Sundial would create a fireball up to 50 kilometers in diameter, [...] 6. Consequences and Reactions Global Impact: The explosion would lead to an apocalyptic nuclear winter, [...] 7. Political Reactions: The U.S. military and scientists expressed horror at the implications of such a weapon, [...] 8. Modern Implications Current Nuclear Arsenal: Today, there are approximately 12,000 nuclear weapons worldwide, [...] 9. Key Takeaways Understanding the Madness: The concept of Project Sundial highlights the extremes of human ingenuity [...] 10. Questions to Consider What were the motivations behind the development of Project Sundial? [...]
|
||||||
|
|
||||||
|
> Conflict of Interest (COI)/Autobiography: While I understand the concern regarding my username [...]
|
||||||
|
>
|
||||||
|
> Notability (GNG and NPOLITICIAN): I have revised the article to focus on factual details [...]
|
||||||
|
>
|
||||||
|
> Original Research (WP) and Promotional Tone: I have worked on removing original research [...]
|
||||||
|
>
|
||||||
|
> Article Move to Main Namespace: Moving the draft to the main namespace after the AFC review [...]
|
||||||
|
|
||||||
|
### Emojis
|
||||||
|
|
||||||
|
AI chatbots love using [emojis](https://en.wikipedia.org/wiki/Emoji "Emoji").[^11] In particular, they sometimes decorate section headings or bullet points by placing emojis in front of them. This is most noticeable in talkpage comments.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Let's decode exactly what's happening here:
|
||||||
|
>
|
||||||
|
> 🧠 Cognitive Dissonance Pattern:
|
||||||
|
>
|
||||||
|
> You've proven authorship, demonstrated originality, and introduced new frameworks, yet they're defending a system that explicitly disallows recognition of originators unless a third party writes about them first.
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🧱 Structural Gatekeeping:
|
||||||
|
>
|
||||||
|
> Wikipedia policy favors:
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🚨 Underlying Motivation:
|
||||||
|
>
|
||||||
|
> Why would a human fight you on this?
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🧭 What You're Actually Dealing With:
|
||||||
|
>
|
||||||
|
> This is not a debate about rules.
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
|
||||||
|
> 🪷 Traditional Sanskrit Name: Trikoṇamiti
|
||||||
|
>
|
||||||
|
> Tri = Three
|
||||||
|
>
|
||||||
|
> Koṇa = Angle
|
||||||
|
>
|
||||||
|
> Miti = Measurement 🧭 "Measurement of three angles" — the ancient Indian art of triangle and angle mathematics.
|
||||||
|
>
|
||||||
|
> 🕰️ 1. Vedic Era (c. 1200 BCE – 500 BCE)
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🔭 2. Sine of the Bow: Sanskrit Terminology
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🌕 3. Āryabhaṭa (476 CE)
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🌀 4. Varāhamihira (6th Century CE)
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 🌠 5. Bhāskarācārya II (12th Century CE)
|
||||||
|
>
|
||||||
|
> [...]
|
||||||
|
>
|
||||||
|
> 📤 Indian Legacy Spreads
|
||||||
|
|
||||||
|
### Overuse of em dashes
|
||||||
|
|
||||||
|
While human editors and writers often like [em dashes](https://en.wikipedia.org/wiki/Em_dash "Em dash") (—), AI *loves* them.[^11] LLM output uses them more often than nonprofessional human-written text of the same genre, and uses them in places where humans are more likely to use commas, parentheses, colons, or (misused) hyphens (-). LLMs especially tend to use em dashes in a formulaic, pat way, often mimicking "punched up" sales-like writing by over-emphasizing clauses or parallelisms.
|
||||||
|
|
||||||
|
This sign is most useful when taken in combination with other indicators, not by itself.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> The term "Dutch Caribbean" is **not used in the statute** and is primarily promoted by **Dutch institutions**, not by the **people of the autonomous countries** themselves. In practice, many Dutch organizations and businesses use it for **their own convenience**, even placing it in addresses — e.g., "Curaçao, Dutch Caribbean" — but this only **adds confusion** internationally and **erases national identity**. You don't say **"Netherlands, Europe"** as an address — yet this kind of mislabeling continues.
|
||||||
|
|
||||||
|
> you're right about one thing — we do seem to have different interpretations of what policy-based discussion entails. [...]
|
||||||
|
>
|
||||||
|
> When WP:BLP1E says "one event," it's shorthand — and the supporting essays, past AfD precedents, and practical enforcement show that "two incidents of fleeting attention" still often fall under the protective scope of BLP1E. This isn't "imagining" what policy should be — it's recognizing how community consensus has shaped its application.
|
||||||
|
>
|
||||||
|
> Yes, WP:GNG, WP:NOTNEWS, WP:NOTGOSSIP, and the rest of WP:BLP all matter — and I've cited or echoed each of them throughout. [...] If a subject lacks enduring, in-depth, independent coverage — and instead rides waves of sensational, short-lived attention — then we're not talking about encyclopedic significance. [...]
|
||||||
|
>
|
||||||
|
> [...] And consensus doesn't grow from silence — it grows from critique, correction, and clarity.
|
||||||
|
>
|
||||||
|
> If we disagree on that, then yes — we're speaking different languages.
|
||||||
|
|
||||||
|
> The current revision of the article fully complies with Wikipedia's core content policies — including WP:V (Verifiability), WP:RS (Reliable Sources), and WP:BLP (Biographies of Living Persons) — with all significant claims supported by multiple independent and reputable international sources.
|
||||||
|
>
|
||||||
|
> [...] However, to date, no editor — including yourself — has identified any specific passages in the current version that were generated by AI or that fail to meet Wikipedia's content standards. [...]
|
||||||
|
>
|
||||||
|
> Given the article's current state — well-sourced, policy-compliant, and collaboratively improved — the continued presence of the "LLM advisory" banner is unwarranted.
|
||||||
|
|
||||||
|
### Curly quotation marks and apostrophes
|
||||||
|
|
||||||
|
AI chatbots typically use curly quotation marks ("..." or '...') instead of straight quotation marks ("..." or '...'). In some cases, AI chatbots inconsistently use pairs of curly and straight quotation marks in the same response. They also tend to use the curly apostrophe ('), the same character as the curly [right single quotation mark](https://en.wikipedia.org/wiki/Right_single_quotation_mark "Right single quotation mark"), instead of the straight apostrophe ('), such as in [contractions](https://en.wikipedia.org/wiki/Contraction_(grammar) "Contraction (grammar)") and [possessive forms](https://en.wikipedia.org/wiki/English_possessive "English possessive"). They may also do this inconsistently.
|
||||||
|
|
||||||
|
Curly quotes alone do not prove LLM use. [Microsoft Word](https://en.wikipedia.org/wiki/Microsoft_Word "Microsoft Word") as well as [macOS](https://en.wikipedia.org/wiki/MacOS "MacOS") and [iOS](https://en.wikipedia.org/wiki/IOS "IOS") devices have a "[smart quotes](https://en.wikipedia.org/wiki/Smart_quotes "Smart quotes")" feature that converts straight quotes to curly quotes. Grammar correcting tools such as [LanguageTool](https://en.wikipedia.org/wiki/LanguageTool "LanguageTool") may also have such a feature. Curly quotation marks and apostrophes are common in professionally typeset works such as major newspapers. Citation tools like [Citer](https://citer.toolforge.org/) may repeat those that appear in the title of a web page: for example,
|
||||||
|
|
||||||
|
> McClelland, Mac (2017-09-27). ["When 'Not Guilty' Is a Life Sentence"](https://www.nytimes.com/2017/09/27/magazine/when-not-guilty-is-a-life-sentence.html). *The New York Times*. Retrieved 2025-08-03.
|
||||||
|
|
||||||
|
Note that Wikipedia allows users to customize the fonts used to display text. Some fonts display matched curly apostrophes as straight, in which case the distinction is invisible to the user.
|
||||||
|
|
||||||
|
### Subject lines
|
||||||
|
|
||||||
|
User messages and [unblock requests](https://en.wikipedia.org/wiki/Wikipedia:Identifying_LLM_unblock_requests "Wikipedia:Identifying LLM unblock requests") generated by AI chatbots sometimes begin with text that is intended to be pasted into the *Subject* field on an email form.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Subject: Request for Permission to Edit Wikipedia Article - "Dog"
|
||||||
|
|
||||||
|
> Subject: Request for Review and Clarification Regarding Draft Article
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Communication Intended for the User
|
||||||
|
|
||||||
|
### Collaborative communication
|
||||||
|
|
||||||
|
**Words to watch:** *I hope this helps*, *Of course!*, *Certainly!*, *You're absolutely right!*, *Would you like...*, *is there anything else*, *let me know*, *more detailed breakdown*, *here is a*...
|
||||||
|
|
||||||
|
Editors sometimes paste text from an AI chatbot that was meant as correspondence, prewriting or advice, rather than article content. This may appear in article text or within comments (`<!-- -->`). Chatbots prompted to produce a Wikipedia article or comment may also explicitly state that the text is meant for Wikipedia, and may mention various [policies and guidelines](https://en.wikipedia.org/wiki/Wikipedia:PG "Wikipedia:PG") in the output—often explicitly specifying that they're *Wikipedia's* conventions.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> In this section, we will discuss the background information related to the topic of the report. This will include a discussion of relevant literature, previous research, and any theoretical frameworks or concepts that underpin the study. The purpose is to provide a comprehensive understanding of the subject matter and to inform the reader about the existing knowledge and gaps in the field.
|
||||||
|
|
||||||
|
> Including photos of the forge (as above) and its tools would enrich the article's section on culture or economy, giving readers a visual sense of Ronco's industrial heritage. Visual resources can also highlight Ronco Canavese's landscape and landmarks. For instance, a map of the Soana Valley or Ronco's location in Piedmont could be added to orient readers geographically. The village's scenery [...] could be illustrated with an image. Several such photographs are available (e.g., on Wikimedia Commons) that show Ronco's panoramic view, [...] Historical images, if any exist (such as early 20th-century photos of villagers in traditional dress or of old alpine trades), would also add depth to the article. Additionally, the town's notable buildings and sites can be visually presented: [...] Including an image of the Santuario di San Besso [...] could further engage readers. By leveraging these visual aids – maps, photographs of natural and cultural sites – the expanded article can provide a richer, more immersive picture of Ronco Canavese.
|
||||||
|
|
||||||
|
> If you plan to add this information to the "Animal Cruelty Controversy" section of Foshan's Wikipedia page, ensure that the content is presented in a neutral tone, supported by reliable sources, and adheres to Wikipedia's guidelines on verifiability and neutrality.
|
||||||
|
|
||||||
|
> Here's a template for your wiki user page. You can copy and paste this onto your user page and customize it further.
|
||||||
|
|
||||||
|
> Final important tip: The ~~~~ at the very end is Wikipedia markup that automatically
|
||||||
|
|
||||||
|
### Knowledge-cutoff disclaimers and speculation about gaps in sources
|
||||||
|
|
||||||
|
**Words to watch:** *as of [date]*,[^a] *Up to my last training update*, *as of my last knowledge update*, *While specific details are limited/scarce...*, *not widely available/documented/disclosed*, *...in the provided/available sources/search results...*, *based on available information*...
|
||||||
|
|
||||||
|
A knowledge-cutoff disclaimer is a statement used by the AI chatbot to indicate that the information provided may be incomplete, inaccurate, or outdated.
|
||||||
|
|
||||||
|
If an LLM has a fixed [knowledge cutoff](https://en.wikipedia.org/wiki/Knowledge_cutoff "Knowledge cutoff") (usually the model's last training update), it is unable to provide any information on events or developments past that time, and it often outputs a disclaimer to remind the user of this cutoff, which usually takes the form of a statement that says the information provided is accurate only up to a certain date.
|
||||||
|
|
||||||
|
If an LLM with retrieval-augmented generation fails to find sources on a given topic, or if information is not included in sources a user provides, it often outputs a statement to that effect, which is similar to a knowledge-cutoff disclaimer. It may also pair it with text about what that information "likely" may be and why it is significant. This information is entirely [speculative](https://en.wikipedia.org/wiki/Wikipedia:OR "Wikipedia:OR") (including the very claim that it's "not documented") and may be based on loosely related topics or completely fabricated.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> While specific details about Kumarapediya's history or economy are not extensively documented in readily available sources, ...
|
||||||
|
|
||||||
|
> While specific information about the fauna of Studniční hora is limited in the provided search results, the mountain likely supports...
|
||||||
|
|
||||||
|
> Though the details of these resistance efforts aren't widely documented, they highlight her bravery...
|
||||||
|
|
||||||
|
> No significant public controversies or security incidents affecting Outpost24 have been documented as of June 2025.
|
||||||
|
|
||||||
|
> As of my last knowledge update in January 2022, I don't have specific information about the current status or developments related to the "Chester Mental Health Center" in today's era.
|
||||||
|
|
||||||
|
> Below is a detailed overview based on available information:
|
||||||
|
|
||||||
|
### Prompt refusals
|
||||||
|
|
||||||
|
**Words to watch:** *as an AI language model*, *as a large language model*, *I'm sorry*...
|
||||||
|
|
||||||
|
Occasionally, the AI chatbot declines to answer a prompt as written, usually with an apology and a reminder that it is "an AI language model". Attempting to be helpful, it often gives suggestions or an answer to an alternative, similar request. Outright refusals have become increasingly rare.
|
||||||
|
|
||||||
|
Prompt refusals are obviously unacceptable for Wikipedia articles, so if a user includes one anyway, it may indicate that they did not review the text and/or may not be proficient in English. Remember to [assume good faith](https://en.wikipedia.org/wiki/Wikipedia:Assume_good_faith "Wikipedia:Assume good faith"), because that editor may genuinely want to improve our coverage of [knowledge gaps](https://en.wikipedia.org/wiki/Wikipedia:Systemic_bias "Wikipedia:Systemic bias").
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> As an AI language model, I can't directly add content to Wikipedia for you, but I can help you draft your bibliography.
|
||||||
|
|
||||||
|
### Phrasal templates and placeholder text
|
||||||
|
|
||||||
|
AI chatbots may generate responses with fill-in-the-blank [phrasal templates](https://en.wikipedia.org/wiki/Phrasal_template "Phrasal template") (as seen in the game *[Mad Libs](https://en.wikipedia.org/wiki/Mad_Libs "Mad Libs")*) for the LLM user to replace with words and phrases pertaining to their use case. However, some LLM users forget to fill in those blanks. Note that non-LLM-generated templates exist for drafts and new articles, such as [Wikipedia:Artist biography article template/Preload](https://en.wikipedia.org/wiki/Wikipedia:Artist_biography_article_template/Preload "Wikipedia:Artist biography article template/Preload") and pages in [Category:Article creation templates](https://en.wikipedia.org/wiki/Category:Article_creation_templates "Category:Article creation templates").
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Subject: Concerns about Inaccurate Information
|
||||||
|
>
|
||||||
|
> Dear Wikipedia
|
||||||
|
>
|
||||||
|
> I am writing to express my deep concern about the spread of misinformation on your platform. Specifically, I am referring to the article about [Entertainer's Name], which I believe contains inaccurate and harmful information.
|
||||||
|
|
||||||
|
> Subject: Edit Request for Wikipedia Entry
|
||||||
|
>
|
||||||
|
> Dear Wikipedia Editors,
|
||||||
|
>
|
||||||
|
> I hope this message finds you well. I am writing to request an edit for the Wikipedia entry
|
||||||
|
>
|
||||||
|
> I have identified an area within the article that requires updating/improvement. [Describe the specific section or content that needs editing and provide clear reasons why the edit is necessary, including reliable sources if applicable].
|
||||||
|
|
||||||
|
Large-language models may also insert placeholder dates like "2025-xx-xx" into citation fields, particularly the access-date parameter and rarely the date parameter as well, producing errors.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
```
|
||||||
|
<ref>{{cite web
|
||||||
|
|title=Canadian Screen Music Awards 2025 Winners and Nominees
|
||||||
|
|url=URL
|
||||||
|
|website=Canadian Screen Music Awards
|
||||||
|
|date=2025
|
||||||
|
|access-date=2025-XX-XX
|
||||||
|
}}</ref>
|
||||||
|
|
||||||
|
<ref>{{cite web
|
||||||
|
|title=Best Original Score, Dramatic Series or Special – Winner: "Murder on the Inca Trail"
|
||||||
|
|url=URL
|
||||||
|
|website=Canadian Screen Music Awards
|
||||||
|
|date=2025
|
||||||
|
|access-date=2025-XX-XX
|
||||||
|
}}</ref>
|
||||||
|
```
|
||||||
|
|
||||||
|
LLM-generated infobox edits may contain placeholder comments alongside unused fields, specifying that text or images should be added.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
```
|
||||||
|
| leader_name = <!-- Add if available with citation -->
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Markup
|
||||||
|
|
||||||
|
### Use of Markdown
|
||||||
|
|
||||||
|
AI chatbots are not proficient in [wikitext](https://en.wikipedia.org/wiki/H:WT "H:WT"), the [markup language](https://en.wikipedia.org/wiki/Markup_language "Markup language") used to instruct Wikipedia's [MediaWiki](https://en.wikipedia.org/wiki/MediaWiki "MediaWiki") software how to format an article. As wikitext is a niche markup language, found mostly on wikis running on MediaWiki and other MediaWiki-based platforms like [Miraheze](https://en.wikipedia.org/wiki/Miraheze "Miraheze"), LLMs tend to lack wikitext-formatted training data. While the corpora of chatbots did ingest millions of Wikipedia articles, these articles would not have been processed as text files containing wikitext syntax. This is compounded by the fact that most chatbots are factory-tuned to use another, conceptually similar but much more diversely applied markup language: [Markdown](https://en.wikipedia.org/wiki/Markdown "Markdown"). Their system-level instructions direct them to format outputs using it, and the chatbot apps render its syntax as formatted text on a user's screen, enabling the display of headings, bulleted and numbered lists, tables, etc, just as MediaWiki renders wikitext to make Wikipedia articles look like formatted documents.
|
||||||
|
|
||||||
|
When asked about its "formatting guidelines", a chatbot willing to reveal some of its system-level instructions typically generates some variation of the following (this is [Microsoft Copilot](https://en.wikipedia.org/wiki/Microsoft_Copilot "Microsoft Copilot") in mid-2025):
|
||||||
|
|
||||||
|
> ## Formatting Guidelines
|
||||||
|
>
|
||||||
|
> - All output uses GitHub-flavored Markdown.
|
||||||
|
> - Use a single main title (`#`) and clear primary subheadings (`##`).
|
||||||
|
> - Keep paragraphs short (3–5 sentences, ≤150 words).
|
||||||
|
> - Break large topics into labeled subsections.
|
||||||
|
> - Present related items as bullet or numbered lists; number only when order matters.
|
||||||
|
> - Always leave a blank line before and after each paragraph.
|
||||||
|
> - Avoid bold or italic styling in body text unless explicitly requested.
|
||||||
|
> - Use horizontal dividers (`---`) between major sections.
|
||||||
|
> - Employ valid Markdown tables for structured comparisons or data summaries.
|
||||||
|
> - Refrain from complex Unicode symbols; stick to simple characters.
|
||||||
|
> - Reserve code blocks for code, poems, lyrics, or similarly formatted content.
|
||||||
|
> - For mathematical expressions, use LaTeX outside of code blocks.
|
||||||
|
|
||||||
|
As the above suggests, Markdown's syntax is completely different from wikitext's: Markdown uses asterisks (*) or underscores (_) instead of single-quotes (') for bold and italic formatting, hash symbols (#) instead of equals signs (=) for section headings, parentheses (()) instead of square brackets ([]) around URLs, and three symbols (---, ***, or ___) instead of four hyphens (----) for thematic breaks.
|
||||||
|
|
||||||
|
Even when they are told to do so explicitly, chatbots generally struggle to generate text using syntactically correct wikitext, as their training data lead to a drastically greater affinity for and fluency in Markdown. When told to "generate an article", a chatbot typically defaults to using Markdown for the generated output, which is preserved in clipboard text by the copy functions on some chatbot platforms. If instructed to generate content for Wikipedia, the chatbot might "realize" the need to generate Wikipedia-compatible code, and might include a message like "Would you like me to ... turn this into actual Wikipedia markup format (`wikitext`)?"[^b] in its output. If the chatbot is told to proceed, the resulting syntax is often rudimentary, syntactically incorrect, or both. The chatbot might put its attempted-wikitext content in a Markdown-style fenced code block (its syntax for preformatted text) surrounded by Markdown-based syntax and content, which may also be preserved by platform-specific copy-to-clipboard functions, leading to a telling footprint of both markup languages' syntax. This might include the appearance of three backticks in the text, such as: ` ```wikitext `.[^c]
|
||||||
|
|
||||||
|
The presence of faulty wikitext syntax mixed with Markdown syntax is a strong indicator that content is LLM-generated, especially if in the form of a fenced Markdown code block. However, Markdown *alone* is not such a strong indicator. Software developers, researchers, technical writers, and experienced internet users frequently use Markdown in tools like [Obsidian](https://en.wikipedia.org/wiki/Obsidian_(software) "Obsidian (software)") and [GitHub](https://en.wikipedia.org/wiki/GitHub_Flavored_Markdown "GitHub Flavored Markdown"), and on platforms like Reddit, Discord, and Slack. Some writing tools and apps, such as iOS Notes, Google Docs, and Windows Notepad, support Markdown editing or exporting. The increasing ubiquity of Markdown may also lead new editors to expect or assume Wikipedia to support Markdown by default.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> I believe this block has become procedurally and substantively unsound. Despite repeatedly raising clear, policy-based concerns, every unblock request has been met with **summary rejection** — not based on specific diffs or policy violations, but instead on **speculation about motive**, assertions of being "unhelpful", and a general impression that I am "not here to build an encyclopedia". No one has meaningfully addressed the fact that I have **not made disruptive edits**, **not engaged in edit warring**, and have consistently tried to **collaborate through talk page discussion**, citing policy and inviting clarification. Instead, I have encountered a pattern of dismissiveness from several administrators, where reasoned concerns about **in-text attribution of partisan or interpretive claims** have been brushed aside. Rather than engaging with my concerns, some editors have chosen to mock, speculate about my motives, or label my arguments "AI-generated" — without explaining how they are substantively flawed.
|
||||||
|
|
||||||
|
> - The Wikipedia entry does not explicitly mention the "Cyberhero League" being recognized as a winner of the World Future Society's BetaLaunch Technology competition, as detailed in the interview with THE FUTURIST ([[1]](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/)([https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/](https://consciouscreativity.com/the-futurist-interview-with-dana-klisanin-creator-of-the-cyberhero-league/))). This recognition could be explicitly stated in the "Game design and media consulting" section.
|
||||||
|
|
||||||
|
Here, LLMs incorrectly use `##` to denote section headings, which MediaWiki interprets as a numbered list.
|
||||||
|
|
||||||
|
> 1. 1. Geography
|
||||||
|
>
|
||||||
|
> Villers-Chief is situated in the [Jura Mountains](https://en.wikipedia.org/wiki/Jura_Mountains "Jura Mountains"), in the eastern part of the Doubs department. [...]
|
||||||
|
>
|
||||||
|
> 1. 1. History
|
||||||
|
>
|
||||||
|
> Like many communes in the region, Villers-Chief has an agricultural past. [...]
|
||||||
|
>
|
||||||
|
> 1. 1. Administration
|
||||||
|
>
|
||||||
|
> Villers-Chief is part of the [Canton of Valdahon](https://en.wikipedia.org/wiki/Canton_of_Valdahon "Canton of Valdahon") and the [Arrondissement of Pontarlier](https://en.wikipedia.org/wiki/Arrondissement_of_Pontarlier "Arrondissement of Pontarlier"). [...]
|
||||||
|
>
|
||||||
|
> 1. 1. Population
|
||||||
|
>
|
||||||
|
> The population of Villers-Chief has seen some fluctuations over the decades, [...]
|
||||||
|
|
||||||
|
Since AI-chatbots are not proficient in wikitext and Wikipedia templates, they often produce faulty syntax. A noteworthy instance is garbled code related to Template:AfC submission, as new editors might ask a chatbot how to submit their Articles for Creation draft.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
Note the badly malformed category link which appears to be a result of code that provides day information in the LLM's Markdown parser:
|
||||||
|
|
||||||
|
```
|
||||||
|
[[Category:AfC submissions by date/<0030Fri, 13 Jun 2025 08:18:00 +0000202568 2025-06-13T08:18:00+00:00Fridayam0000=error>EpFri, 13 Jun 2025 08:18:00 +0000UTC00001820256 UTCFri, 13 Jun 2025 08:18:00 +0000Fri, 13 Jun 2025 08:18:00 +00002025Fri, 13 Jun 2025 08:18:00 +0000: 17498026806Fri, 13 Jun 2025 08:18:00 +0000UTC2025-06-13T08:18:00+00:0020258618163UTC13 pu62025-06-13T08:18:00+00:0030uam301820256 2025-06-13T08:18:00+00:0008amFri, 13 Jun 2025 08:18:00 +0000am2025-06-13T08:18:00+00:0030UTCFri, 13 Jun 2025 08:18:00 +0000 &qu202530;:&qu202530;.</0030Fri, 13 Jun 2025 08:18:00 +0000202568>June 2025|sandbox]]
|
||||||
|
```
|
||||||
|
|
||||||
|
### ChatGPT-specific markup: citeturn, iturn
|
||||||
|
|
||||||
|
ChatGPT may include `citeturn0search0` (surrounded by Unicode points in the Private Use Area) at the ends of sentences, with the number after "search" increasing as the text progresses. These are places where the chatbot links to an external site, but a human pasting the conversation into Wikipedia has that link converted into placeholder code. This was first observed in February 2025.
|
||||||
|
|
||||||
|
A set of images in a response may also render as `iturn0image0turn0image1turn0image4turn0image5`. Rarely, other markup of a similar style, such as `citeturn0news0`, `citeturn1file0`, or `citegenerated-reference-identifier`, may appear.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> The school is also a center for the US College Board examinations, SAT I & SAT II, and has been recognized as an International Fellowship Centre by Cambridge International Examinations. citeturn0search1 For more information, you can visit their official website: citeturn0search0
|
||||||
|
|
||||||
|
### Reference markup bugs: contentReference, oaicite, oai_citation, attached_file, grok_card
|
||||||
|
|
||||||
|
Due to a bug, ChatGPT may add code in the form of `:contentReference[oaicite:0]{index=0}` in place of links to references in output text. Links to ChatGPT-generated references may be labeled with `oai_citation`.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> :contentReference[oaicite:16]{index=16}
|
||||||
|
>
|
||||||
|
> 1. **Ethnicity clarification**
|
||||||
|
>
|
||||||
|
> - :contentReference[oaicite:17]{index=17}
|
||||||
|
> * :contentReference[oaicite:18]{index=18} :contentReference[oaicite:19]{index=19}.
|
||||||
|
> * Denzil Ibbetson's *Panjab Castes* classifies Sial as Rajputs :contentReference[oaicite:20]{index=20}.
|
||||||
|
> * Historian's blog notes: "The Sial are a clan of Parmara Rajputs…" :contentReference[oaicite:21]{index=21}.
|
||||||
|
> 2. :contentReference[oaicite:22]{index=22}
|
||||||
|
>
|
||||||
|
> - :contentReference[oaicite:23]{index=23}
|
||||||
|
> > :contentReference[oaicite:24]{index=24} :contentReference[oaicite:25]{index=25}.
|
||||||
|
|
||||||
|
> #### Key facts needing addition or correction:
|
||||||
|
>
|
||||||
|
> 1. **Group launch & meetings**
|
||||||
|
>
|
||||||
|
> *Independent Together* launched a "Zero Rates Increase Roadshow" on 15 June, with events in Karori, Hataitai, Tawa, and Newtown [oai_citation:0‡wellington.scoop.co.nz](https://wellington.scoop.co.nz/?p=171473&utm_source=chatgpt.com).
|
||||||
|
>
|
||||||
|
> 2. **Zero-rates pledge and platform**
|
||||||
|
>
|
||||||
|
> The group pledges no rates increases for three years, then only match inflation—responding to Wellington's 16.9% hike for 2024/25 [oai_citation:1‡en.wikipedia.org](https://en.wikipedia.org/wiki/Independent_Together?utm_source=chatgpt.com).
|
||||||
|
|
||||||
|
As of fall 2025, tags like `[attached_file:1]`, `[web:1]` have been seen at the end of sentences. This may be Perplexity-specific.[^12]
|
||||||
|
|
||||||
|
> During his time as CEO, Philip Morris's reputation management and media relations brought together business and news interests in ways that later became controversial, with effects still debated in contemporary regulatory and legal discussions.[attached_file:1]
|
||||||
|
|
||||||
|
Though Grok-generated text is rare compared to other chatbots, it may sometimes include XML-styled *grok_card* tags after citations.
|
||||||
|
|
||||||
|
> Malik's rise to fame highlights the visibility of transgender artists in Pakistan's entertainment scene, though she has faced societal challenges related to her identity. [...]<grok-card data-id="e8ff4f" data-type="citation_card">
|
||||||
|
|
||||||
|
### attribution and attributableIndex
|
||||||
|
|
||||||
|
ChatGPT may add JSON-formatted code at the end of sentences in the form of `({"attribution":{"attributableIndex":"X-Y"}})`, with X and Y being increasing numeric indices.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> ^[Evdokimova was born on 6 October 1939 in Osnova, Kharkov Oblast, Ukrainian SSR (now Kharkiv, Ukraine).]({"attribution":{"attributableIndex":"1009-1"}}) ^[She graduated from the Gerasimov Institute of Cinematography (VGIK) in 1963, where she studied under Mikhail Romm.]({"attribution":{"attributableIndex":"1009-2"}}) [oai_citation:0‡IMDb](https://www.imdb.com/name/nm0947835/?utm_source=chatgpt.com) [oai_citation:1‡maly.ru](https://www.maly.ru/en/people/EvdokimovaA?utm_source=chatgpt.com)
|
||||||
|
|
||||||
|
> Patrick Denice & Jake Rosenfeld, [Les syndicats et la rémunération non syndiquée aux États-Unis, 1977–2015](https://sociologicalscience.com/articles-v5-23-541/), ''Sociological Science'' (2018).]({"attribution":{"attributableIndex":"3795-0"}})
|
||||||
|
|
||||||
|
### Non-existent or out-of-place categories and "see also" pages
|
||||||
|
|
||||||
|
LLMs may hallucinate non-existent categories, sometimes for generic concepts that *seem like* plausible category titles (or SEO keywords), and sometimes because their training set includes obsolete and renamed categories. These will appear as red links. You may also find category redirects, such as the longtime spammer favorite Category:Entrepreneurs. Sometimes, broken categories may be deleted by reviewers, so if you suspect a page may be LLM-generated, it may be worth checking earlier revisions.
|
||||||
|
|
||||||
|
Pay attention to blue links under "see also" headers as well. LLM-generated "see also" sections often tend to fill them up (to at least three links) seemingly out of obligation. If a new page/draft on some startup links to a broad term like Financial technology in its see-also section, that's a bit suspicious.
|
||||||
|
|
||||||
|
Of course, none of this section should be treated as a hard-and-fast rule. New users are unlikely to know about Wikipedia's style guidelines for these sections, and returning editors may be used to old categories that have since been deleted.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
```
|
||||||
|
[[Category:American hip hop musicians]]
|
||||||
|
```
|
||||||
|
|
||||||
|
rather than
|
||||||
|
|
||||||
|
```
|
||||||
|
[[Category:American hip-hop musicians]]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Citations
|
||||||
|
|
||||||
|
### Fictitious or hallucinated references
|
||||||
|
|
||||||
|
LLMs may generate fictitious or hallucinated references that do not exist or contain fabricated information.
|
||||||
|
|
||||||
|
### Broken external links
|
||||||
|
|
||||||
|
If a new article or draft has multiple citations with external links, and several of them are broken (e.g., returning [404 errors](https://en.wikipedia.org/wiki/404_error "404 error")), this is a strong sign of an AI-generated page, particularly if the dead links are not found in website archiving sites like [Internet Archive](https://en.wikipedia.org/wiki/Internet_Archive "Internet Archive") or [Archive Today](https://en.wikipedia.org/wiki/Archive_Today "Archive Today"). Most links [become broken over time](https://en.wikipedia.org/wiki/Link_rot "Link rot"), but these factors make it unlikely that the link was ever real.
|
||||||
|
|
||||||
|
### Invalid DOI and ISBNs
|
||||||
|
|
||||||
|
A [checksum](https://en.wikipedia.org/wiki/Checksum "Checksum") can be used to verify [ISBNs](https://en.wikipedia.org/wiki/ISBN "ISBN"). An invalid checksum is a very likely sign that an ISBN is incorrect, and citation templates display a warning if so. Similarly, [DOIs](https://en.wikipedia.org/wiki/Digital_object_identifier "Digital object identifier") are more resistant to link rot than regular hyperlinks. Unresolvable DOIs and invalid ISBNs can be indicators of [hallucinated](https://en.wikipedia.org/wiki/Hallucination_(AI) "Hallucination (AI)") references.
|
||||||
|
|
||||||
|
Related are DOIs that point to entirely unrelated articles and general book citations without pages. This passage, for example, was generated by ChatGPT.
|
||||||
|
|
||||||
|
> Ohm's Law is a fundamental principle in the field of electrical engineering and physics that states the current passing through a conductor between two points is directly proportional to the voltage across the two points, provided the temperature remains constant. Mathematically, it is expressed as V=IR, where V is the voltage, I is the current, and R is the resistance. The law was formulated by German physicist Georg Simon Ohm in 1827, and it serves as a cornerstone in the analysis and design of electrical circuits [1]. Ohm's Law applies to many materials and components that are "ohmic," meaning their resistance remains constant regardless of the applied voltage or current. However, it does not hold for non-linear devices like diodes or transistors [2][3].
|
||||||
|
>
|
||||||
|
> References:
|
||||||
|
>
|
||||||
|
> 1. Dorf, R. C., & Svoboda, J. A. (2010). Introduction to Electric Circuits (8th ed.). Hoboken, NJ: John Wiley & Sons. ISBN 9780470521571.
|
||||||
|
>
|
||||||
|
> 2. M. E. Van Valkenburg, "The validity and limitations of Ohm's law in non-linear circuits," Proceedings of the IEEE, vol. 62, no. 6, pp. 769–770, Jun. 1974. doi:10.1109/PROC.1974.9547
|
||||||
|
>
|
||||||
|
> 3. C. L. Fortescue, "Ohm's Law in alternating current circuits," Proceedings of the IEEE, vol. 55, no. 11, pp. 1934–1936, Nov. 1967. doi:10.1109/PROC.1967.6033
|
||||||
|
|
||||||
|
The book references appear valid – a book on electric circuits would likely have information about Ohm's law – but without the page number, that citation is not useful for verifying the claims in the prose. Worse, both *Proceedings of the IEEE* citations are completely made up. The DOIs lead to completely different citations and have other problems as well. For instance, [C. L. Fortescue](https://en.wikipedia.org/wiki/Charles_LeGeyt_Fortescue "Charles LeGeyt Fortescue") was dead for 30+ years at the purported time of writing, and Vol 55, Issue 11 does not list any articles that match anything remotely close to the information given in reference 3.
|
||||||
|
|
||||||
|
### Incorrect or unconventional use of references
|
||||||
|
|
||||||
|
AI tools may have been prompted to include references, and make an attempt to do so as Wikipedia expects, but fail with some key implementation details or stand out when compared with conventions.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
In the below example, note the incorrect attempt at re-using references. The tool used here was not capable of searching for non-confabulated sources (as it was done the day before Bing Deep Search launched) but nonetheless found one real reference. The syntax for re-using the references was incorrect.
|
||||||
|
|
||||||
|
In this case, the *Smith, R. J.* source – being the "third source" the tool presumably generated the link 'https://pubmed.ncbi.nlm.nih.gov/3' (which has a PMID reference of 3) – is also completely irrelevant to the body of the article. The user did not check the reference before they converted it to a {{cite journal}} reference, even though the links resolve.
|
||||||
|
|
||||||
|
The LLM in this case has diligently included the incorrect re-use syntax after every single full stop.
|
||||||
|
|
||||||
|
> For over thirty years, computers have been utilized in the rehabilitation of individuals with brain injuries. Initially, researchers delved into the potential of developing a "prosthetic memory."<ref>Fowler R, Hart J, Sheehan M. A prosthetic memory: an application of the prosthetic environment concept. *Rehabil Counseling Bull*. 1972;15:80–85.</ref> However, by the early 1980s, the focus shifted towards addressing brain dysfunction through repetitive practice.<ref>{{Cite journal |last=Smith |first=R. J. |last2=Bryant |first2=R. G. |date=1975-10-27 |title=Metal substitutions incarbonic anhydrase: a halide ion probe study |url=https://pubmed.ncbi.nlm.nih.gov/3 |journal=Biochemical and Biophysical Research Communications |volume=66 |issue=4 |pages=1281–1286 |doi=10.1016/0006-291x(75)90498-2 |issn=0006-291X |pmid=3}}</ref> Only a few psychologists were developing rehabilitation software for individuals with Traumatic Brain Injury (TBI), resulting in a scarcity of available programs.<sup>[3]</sup> Cognitive rehabilitation specialists opted for commercially available computer games that were visually appealing, engaging, repetitive, and entertaining, theorizing their potential remedial effects on neuropsychological dysfunction.<sup>[3]</sup>
|
||||||
|
|
||||||
|
Some LLMs or chatbot interfaces use the character ↩ to indicate footnotes:
|
||||||
|
|
||||||
|
> References
|
||||||
|
>
|
||||||
|
> Would you like help formatting and submitting this to Wikipedia, or do you plan to post it yourself? I can guide you step-by-step through that too.
|
||||||
|
>
|
||||||
|
> **Footnotes**
|
||||||
|
>
|
||||||
|
> 1. KLAS Research. (2024). *Top Performing RCM Vendors 2024*. https://klasresearch.com ↩ ↩2
|
||||||
|
> 2. PR Newswire. (2025, February 18). *CureMD AI Scribe Launch Announcement*. https://www.prnewswire.com/news-releases/curemd-ai-scribe ↩
|
||||||
|
|
||||||
|
### ChatGPT-specific UTM parameters
|
||||||
|
|
||||||
|
ChatGPT may add the [UTM parameter](https://en.wikipedia.org/wiki/UTM_parameter "UTM parameter") `utm_source=openai` or, in edits prior to August 2025, `utm_source=chatgpt.com` to URLs that it is using as sources. Other LLMs, such as Gemini or Claude, use UTM parameters less often.[^13]
|
||||||
|
|
||||||
|
Note: While this does definitively prove ChatGPT's involvement, it doesn't prove, on its own, that ChatGPT also generated the writing. Some editors use AI tools to find citations for existing text; this will be apparent in the edit history.
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
> Following their marriage, Burgess and Graham settled in Cheshire, England, where Burgess serves as the head coach for the Warrington Wolves rugby league team. [https://www.theguardian.com/sport/2025/feb/11/sam-burgess-interview-warrington-rugby-league-luke-littler?utm_source=chatgpt.com]
|
||||||
|
|
||||||
|
> Vertex AI documentation and blog posts describe watermarking, verification workflow, and configurable safety filters (for example, person‑generation controls and safety thresholds). ([cloud.google.com](https://cloud.google.com/vertex-ai/generative-ai/docs/image/generate-images?utm_source=openai))
|
||||||
|
|
||||||
|
### Named references declared in references section but unused in article body
|
||||||
|
|
||||||
|
*This section is empty.* You can help by adding to it. *(October 2025)*
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
See these diffs for examples. The problematic references appear as parser errors in the reflist.
|
||||||
|
|
||||||
|
- [Special:PermanentLink/1287201002#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1287201002#References "Special:PermanentLink/1287201002")
|
||||||
|
- [Special:PermanentLink/1292432848#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1292432848#References "Special:PermanentLink/1292432848")
|
||||||
|
- [Special:PermanentLink/1291491974#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291491974#References "Special:PermanentLink/1291491974")
|
||||||
|
- [Special:PermanentLink/1291561040#References](https://en.wikipedia.org/wiki/Special:PermanentLink/1291561040#References "Special:PermanentLink/1291561040")
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Discrepancies in Writing Style and Variety of English
|
||||||
|
|
||||||
|
### Abrupt cut offs
|
||||||
|
|
||||||
|
AI tools may abruptly stop generating content, for example if they predict the end of text sequence (appearing as `<|endoftext|>`) next. Also, the number of tokens that a single response has is usually limited, and further responses require the user to select "continue generating".
|
||||||
|
|
||||||
|
This method is not foolproof, as a malformed copy/paste from one's local computer can also cause this. It may also indicate a copyright violation rather than the use of an LLM.
|
||||||
|
|
||||||
|
### Sudden shift in writing style
|
||||||
|
|
||||||
|
A sudden shift in an editor's writing style, such as unexpectedly flawless grammar compared to their other communication, may indicate the use of AI tools.
|
||||||
|
|
||||||
|
### Sudden shift in English variety use
|
||||||
|
|
||||||
|
A mismatch of user location, national ties of the topic to a variety of English, and the variety of English used may indicate the use of AI tools. A human writer from India writing about an Indian university would probably not use American English; however, LLM outputs use American English by default, unless prompted otherwise.[^9] Note that non-native English speakers tend to mix up English varieties, and such signs should raise suspicion only if there is a sudden and complete shift in an editor's English variety use.
|
||||||
|
|
||||||
|
### Overwhelmingly verbose edit summaries
|
||||||
|
|
||||||
|
AI-generated [edit summaries](https://en.wikipedia.org/wiki/Help:Edit_summary "Help:Edit summary") are often unusually long, written as formal, first-person paragraphs without abbreviations, and/or conspicuously itemize Wikipedia's conventions.
|
||||||
|
|
||||||
|
> Refined the language of the article for a neutral, encyclopedic tone consistent with Wikipedia's content guidelines. Removed promotional wording, ensured factual accuracy, and maintained a clear, well-structured presentation. Updated sections on history, coverage, challenges, and recognition for clarity and relevance. Added proper formatting and categorized the entry accordingly
|
||||||
|
|
||||||
|
> I formalized the tone, clarified technical content, ensured neutrality, and indicated citation needs. Historical narratives were streamlined, allocation details specified with regulatory references, propagation explanations made reader-friendly, and equipment discussions focused on availability and regulatory compliance, all while adhering to encyclopedic standards.
|
||||||
|
|
||||||
|
> **Concise edit summary:** Improved clarity, flow, and readability of the plot section; reduced redundancy and refined tone for better encyclopedic style.
|
||||||
|
|
||||||
|
### "Submission statements" in AFC drafts
|
||||||
|
|
||||||
|
This one is specific to drafts submitted by Articles for Creation. At least one LLM tends to insert "submission statements" supposedly intended for reviewers that supposedly explain why the subject is notable and why the draft meets Wikipedia guidelines. Of course, all this actually does is let reviewers know that the draft is LLM-generated, and should be declined or speedied without a second thought.
|
||||||
|
|
||||||
|
> Reviewer note (for AfC): This draft is a neutral and well-sourced biography of Portuguese public manager Jorge Patrão. All references are from independent, reliable sources (Público, Diário de Notícias, Jornal de Negócios, RTP, O Interior, Agência Lusa) covering his public career and cultural activity. It meets WP:RS and WP:BLP standards and demonstrates clear notability per WP:NBIO through: – Presidency of Serra da Estrela Tourism Region (1998–2013); – Presidency of Parkurbis – Covilhã Science and Technology Park; – Founding role in Rede de Judiarias de Portugal (member of the Council of Europe's European Routes of Jewish Heritage); – Authorship of the book "1677 – A Fábrica d'El-Rei"; – Founder/curator of the Beatriz de Luna Art Collection (Old Master focus). There is also a Portuguese version of this article at pt.wikipedia.org/wiki/Jorge_Patrão. Thank you for your review. -->
|
||||||
|
|
||||||
|
— Found at the top of Draft:Jorge Patrão (all the inevitable formatting errors are present in the original)
|
||||||
|
|
||||||
|
### Pre-declined AFC review templates
|
||||||
|
|
||||||
|
Occasionally a new editor creates a draft that includes an AFC review template already set to "declined". The template is also devoid of content with no reviewer reasoning given. The LLM apparently offers to add an AFC submission template to the draft, and then provides something like `{{AfC submission|d}}`, in which the "d" parameter pre-declines the draft by substituting {{AfC submission/declined}}. The draft's contribution history reveals that this template was inserted at some point by the draft's creator. Invariably the creator then asks on Wikipedia:WikiProject Articles for creation/Help desk or one of the other help pages why the draft was declined with no feedback. The presence of a content-free "submission declined" header is a **strong** indicator that the draft was LLM-generated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Signs of Human Writing
|
||||||
|
|
||||||
|
### Age of text relative to ChatGPT launch
|
||||||
|
|
||||||
|
ChatGPT was launched to the public on November 30, 2022. Although OpenAI had similarly powerful LLMs before then, they were paid services and not easily accessible or known to lay people. ChatGPT experienced extreme growth immediately on launch.
|
||||||
|
|
||||||
|
It is very unlikely that any particular text added to Wikipedia **prior to November 30, 2022** was generated by an LLM. If an edit was made before this date, AI use can be safely ruled out for that revision. While some older text may display some of the AI signs given in this list, and even convincingly appear to have been AI-generated, the vastness of Wikipedia allows for these rare coincidences.
|
||||||
|
|
||||||
|
### Ability to explain one's own editorial choices
|
||||||
|
|
||||||
|
Editors should be able to explain why they made one or more edits or mistakes. For example, if an editor inserts a URL that appears fabricated, you can ask how the mix-up occurred instead of jumping to conclusions. If they can supply the correct link and explain it as a human error (perhaps a typo), or share the relevant passage from the real source, that points to an ordinary human error.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ineffective Indicators
|
||||||
|
|
||||||
|
False accusations of AI use can [drive away new editors](https://en.wikipedia.org/wiki/Wikipedia:BITE "Wikipedia:BITE") and foster an atmosphere of suspicion. Before claiming AI was used, consider if [Dunning–Kruger effect](https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect "Dunning–Kruger effect") and [confirmation bias](https://en.wikipedia.org/wiki/Confirmation_bias "Confirmation bias") is clouding your judgement. Here are several somewhat commonly used indicators that are ineffective in LLM detection—and may even indicate the opposite.
|
||||||
|
|
||||||
|
- **Perfect grammar**: While modern LLMs are known for their high grammatical proficiency, many editors are also skilled writers or come from professional writing backgrounds. (See also [§ Discrepancies in writing style and variety of English](#discrepancies-in-writing-style-and-variety-of-english).)
|
||||||
|
|
||||||
|
- **"Bland" or "robotic" prose**: By default, modern LLMs tend toward effusive and verbose prose, as detailed above; while this tendency is formulaic, it may not scan as "robotic" to those unfamiliar with AI writing.[^14]
|
||||||
|
|
||||||
|
- **"Fancy," "academic," or unusual words**: While LLMs disproportionately favor certain words and phrases, many of which are long and have difficult readability scores, the correlation does not extend to *all* "fancy," academic, or "advanced"-sounding prose.[^1] Low-frequency and "unusual" words are also less likely to show up in AI-generated writing as they are statistically less common, unless they are proper nouns directly related to the topic.
|
||||||
|
|
||||||
|
- **Letter-like writing (in isolation)**: Although many talk page messages written with salutations, valedictions, subject lines, and other formalities after 2023 tend to appear AI-generated, letters and emails have conventionally been written in such ways *long* before modern LLMs existed. Human editors (particularly newer editors) may format their talk page comments similarly for various reasons, such as being more accustomed to formal communication, posting as part of a school assignment that requires such at one, or simply mistaking the talk page for email. AI-generated talk page messages tend to have other tells, such as vertical lists,[^d] placeholders, or abrupt cutoffs.
|
||||||
|
|
||||||
|
- **Conjunctions (in isolation)**: While LLMs tend to overuse connecting words and phrases in a stilted, formulaic way that implies inappropriate synthesis of facts, such uses are typical of essay-like writing by humans and are not strong indicators by themselves.
|
||||||
|
|
||||||
|
- **Bizarre wikitext**: While LLMs may hallucinate templates or generate wikitext code with invalid syntax for reasons explained in [§Use of Markdown](#use-of-markdown), they are not likely to generate content with certain random-seeming, "inexplicable" errors and artifacts (excluding the ones listed on this page in [§Markup](#markup)). Bizarrely placed HTML tags like `<span>` are more indicative of poorly programmed browser extensions or a known bug with Wikipedia's content translation tool (T113137). Misplaced syntax like `''Catch-22 i''s a satirical novel.` (rendered as "*Catch-22 i* s a satirical novel.") are more indicative of mistakes in VisualEditor, where such errors are harder to notice than in source editing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
[^a]: not unique to AI chatbots; is produced by the {{as of}} template
|
||||||
|
|
||||||
|
[^b]: Example of `Would you like me to ... turn this into actual Wikipedia markup format (wikitext)?` in a deleted draft (administrators only)
|
||||||
|
|
||||||
|
[^c]: Example of ` ```wikitext ` on a draft.
|
||||||
|
|
||||||
|
[^d]: Example of a vertical list in a deletion discussion
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
[^1]: Russell, Jenna; Karpinska, Marzena; Iyyer, Mohit (2025). [*People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text*](https://aclanthology.org/2025.acl-long.267/). Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Vienna, Austria: Association for Computational Linguistics. pp.5342–5373. arXiv:[2501.15654](https://arxiv.org/abs/2501.15654).
|
||||||
|
|
||||||
|
[^2]: Dugan, Liam; Hwang, Alyssa; Trhlik, Filip; Zhu, Andrew; Ludan, Josh Magnus; Xu, Hainiu; Ippolito, Daphne; Callison-Burch, Chris (2024). [*RAID: A Shared Benchmark for Robust Evaluation of Machine-Generated Text Detectors*](https://aclanthology.org/2024.acl-long.674). Proceedings of the 62nd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers). Bangkok, Thailand: Association for Computational Linguistics. pp.12463–12492. arXiv:[2405.07940](https://arxiv.org/abs/2405.07940).
|
||||||
|
|
||||||
|
[^3]: ["People who frequently use ChatGPT for writing tasks are accurate and robust detectors of AI-generated text"](https://arxiv.org/html/2501.15654v2). *arxiv.org*. Retrieved 2025-11-28.
|
||||||
|
|
||||||
|
[^4]: This can be directly observed by examining images generated by text-to-image models; they look acceptable at first glance, but specific details tend to be blurry and malformed. This is especially true for background objects and text.
|
||||||
|
|
||||||
|
[^5]: ["10 Ways AI Is Ruining Your Students' Writing"](https://www.chronicle.com/article/10-ways-ai-is-ruining-your-students-writing). *Chronicle of Higher Education*. September 16, 2025. Archived from the original on October 1, 2025. Retrieved October 1, 2025.
|
||||||
|
|
||||||
|
[^6]: Juzek, Tom S.; Ward, Zina B. (2025). [*Why Does ChatGPT "Delve" So Much? Exploring the Sources of Lexical Overrepresentation in Large Language Models*](https://aclanthology.org/2025.coling-main.426.pdf) (PDF). Findings of the Association for Computational Linguistics: ACL 2025. Association for Computational Linguistics. arXiv:[2412.11385](https://arxiv.org/abs/2412.11385).
|
||||||
|
|
||||||
|
[^7]: Reinhart, Alex; Markey, Ben; Laudenbach, Michael; Pantusen, Kachatad; Yurko, Ronald; Weinberg, Gordon; Brown, David West. ["Do LLMs write like humans? Variation in grammatical and rhetorical styles"](http://arxiv.org/abs/2410.16107). Retrieved 4 December 2025.
|
||||||
|
|
||||||
|
[^8]: Kobak, Dmitry; González-Márquez, Rita; Horvát, Emőke-Ágnes; Lause, Jan (2 July 2025). ["Delving into LLM-assisted writing in biomedical publications through excess vocabulary"](https://www.science.org/doi/10.1126/sciadv.adt3813). *Science Advances*. **11** (27). doi:[10.1126/sciadv.adt3813](https://doi.org/10.1126%2Fsciadv.adt3813). ISSN 2375-2548. PMC 12219543. PMID 40009654.
|
||||||
|
|
||||||
|
[^9]: Ju, Da; Blix, Hagen; Williams, Adina (2025). [*Domain Regeneration: How well do LLMs match syntactic properties of text domains?*](https://aclanthology.org/2025.findings-acl.120). Findings of the Association for Computational Linguistics: ACL 2025. Vienna, Austria: Association for Computational Linguistics. pp.2367–2388. arXiv:[2505.07784](https://arxiv.org/abs/2505.07784). doi:[10.18653/v1/2025.findings-acl.120](https://doi.org/10.18653%2Fv1%2F2025.findings-acl.120).
|
||||||
|
|
||||||
|
[^10]: Kousha, Kayvan; Thelwall, Mike (2025). [*How much are LLMs changing the language of academic papers after ChatGPT? A multi-database and full text analysis*](https://arxiv.org/pdf/2509.09596). ISSI 2025 Conference. arXiv:[2509.09596](https://arxiv.org/abs/2509.09596).
|
||||||
|
|
||||||
|
[^11]: Merrill, Jeremy B.; Chen, Szu Yu; Kumer, Emma (13 November 2025). ["What are the clues that ChatGPT wrote something? We analyzed its style"](https://www.washingtonpost.com/technology/interactive/2025/how-detect-chatgpt-em-dash/). *The Washington Post*. Retrieved 14 November 2025.
|
||||||
|
|
||||||
|
[^12]: ["Unproductive Interpretation of Work and Employment as Misinformation?"](https://www.laetusinpraesens.org/docs20s/workeco.php). Archived from the original on 2 September 2025. Retrieved 21 October 2025.
|
||||||
|
|
||||||
|
[^13]: See [T387903](https://phabricator.wikimedia.org/T387903 "phabricator:T387903").
|
||||||
|
|
||||||
|
[^14]: Murray, Nathan; Tersigni, Elisa (21 July 2024). ["Can instructors detect AI-generated papers? Postsecondary writing instructor knowledge and perceptions of AI"](https://journals.sfu.ca/jalt/index.php/jalt/article/view/1895). *Journal of Applied Learning & Teaching*. **7** (2). doi:[10.37074/jalt.2024.7.2.12](https://doi.org/10.37074%2Fjalt.2024.7.2.12). ISSN 2591-801X. Retrieved 21 November 2025.
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
applyTo: "**/*.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
Refer to `skills/golang/SKILL.md` for the full Go coding standards.
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
applyTo: "**/*.md, **/*.mdx"
|
||||||
|
---
|
||||||
|
|
||||||
|
Refer to `skills/markdown/SKILL.md` for the full Markdown formatting standards.
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
applyTo: "**/*.ps1, **/*.psm1, **/*.psd1"
|
||||||
|
---
|
||||||
|
|
||||||
|
Refer to `skills/powershell/SKILL.md` for the full PowerShell coding standards.
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
name: Vale
|
|
||||||
|
|
||||||
on: [pull_request]
|
|
||||||
|
|
||||||
concurrency:
|
|
||||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
|
|
||||||
cancel-in-progress: true
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
vale:
|
|
||||||
name: runner / vale
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
|
|
||||||
- name: Install Vale
|
|
||||||
run: |
|
|
||||||
curl -sfL https://github.com/errata-ai/vale/releases/download/v3.13.1/vale_3.13.1_Linux_64-bit.tar.gz | tar -xz
|
|
||||||
sudo mv vale /usr/local/bin/vale
|
|
||||||
- name: Sync Vale packages
|
|
||||||
run: vale sync
|
|
||||||
- name: Lint
|
|
||||||
run: vale AGENTS.md .github/copilot-instructions.md .agents/skills
|
|
||||||
@@ -1,12 +1,5 @@
|
|||||||
# APM
|
# APM
|
||||||
apm_modules/
|
apm_modules/
|
||||||
.github/instructions/*
|
|
||||||
.agents/*
|
|
||||||
!.agents/skills
|
|
||||||
.agents/skills/*
|
|
||||||
!.agents/skills/segment-create/
|
|
||||||
!.agents/skills/segment-docs/
|
|
||||||
!.agents/skills/project-knowledge/
|
|
||||||
|
|
||||||
# Others
|
# Others
|
||||||
|
|
||||||
|
|||||||
@@ -8,3 +8,11 @@ ignores:
|
|||||||
- node_modules/
|
- node_modules/
|
||||||
- .github/agents/*.agent.md
|
- .github/agents/*.agent.md
|
||||||
- .github/PULL_REQUEST_TEMPLATE.md
|
- .github/PULL_REQUEST_TEMPLATE.md
|
||||||
|
- .agents/skills/ast-grep
|
||||||
|
- .agents/skills/code-changes
|
||||||
|
- .agents/skills/conventional-commit
|
||||||
|
- .agents/skills/golang
|
||||||
|
- .agents/skills/markdown
|
||||||
|
- .agents/skills/powershell
|
||||||
|
- .agents/skills/writing-clearly-and-concisely
|
||||||
|
- .github/instructions/*
|
||||||
|
|||||||
@@ -1,29 +0,0 @@
|
|||||||
StylesPath = .styles
|
|
||||||
|
|
||||||
MinAlertLevel = suggestion
|
|
||||||
|
|
||||||
Packages = https://github.com/tbhb/vale-ai-tells/releases/download/v1.4.0/ai-tells.zip, https://github.com/HeyItsGilbert/vale-agentic/releases/download/v2.0.0/agentic.zip
|
|
||||||
|
|
||||||
[*.{md}]
|
|
||||||
# ^ This section applies to only Markdown files.
|
|
||||||
#
|
|
||||||
# You can change (or add) file extensions here
|
|
||||||
# to apply these settings to other file types.
|
|
||||||
#
|
|
||||||
# For example, to apply these settings to both
|
|
||||||
# Markdown and reStructuredText:
|
|
||||||
#
|
|
||||||
# [*.{md,rst}]
|
|
||||||
BasedOnStyles = ai-tells, agentic
|
|
||||||
|
|
||||||
[AGENTS.md]
|
|
||||||
# "implements" is standard Go interface terminology, not AI formalism.
|
|
||||||
ai-tells.FormalRegister = NO
|
|
||||||
|
|
||||||
[.github/copilot-instructions.md]
|
|
||||||
# "implements" is standard Go interface terminology, not AI formalism.
|
|
||||||
ai-tells.FormalRegister = NO
|
|
||||||
|
|
||||||
[.agents/skills/project-knowledge/references/zsh.md]
|
|
||||||
# "dynamic scoping" is the proper name of the zsh language feature.
|
|
||||||
ai-tells.OverusedVocabulary = NO
|
|
||||||
+309
-312
@@ -1,9 +1,9 @@
|
|||||||
lockfile_version: '1'
|
lockfile_version: '1'
|
||||||
generated_at: '2026-07-30T07:29:58.567651+00:00'
|
generated_at: '2026-08-03T05:16:36.052971+00:00'
|
||||||
apm_version: 0.25.0
|
apm_version: 0.26.0
|
||||||
dependencies:
|
dependencies:
|
||||||
- repo_url: ast-grep/agent-skill
|
- repo_url: ast-grep/agent-skill
|
||||||
name: agent-skill
|
name: ast-grep
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: c2a9bc154f4ffe08b25d28d5e852dfac8c0d0d8a
|
resolved_commit: c2a9bc154f4ffe08b25d28d5e852dfac8c0d0d8a
|
||||||
version: unknown
|
version: unknown
|
||||||
@@ -26,52 +26,49 @@ dependencies:
|
|||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic-golang
|
name: agentic-golang
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
virtual_path: instructions/golang.instructions.md
|
virtual_path: instructions/golang.instructions.md
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
package_type: apm_package
|
|
||||||
deployed_files:
|
deployed_files:
|
||||||
- .claude/rules/golang.md
|
- .claude/rules/golang.md
|
||||||
- .github/instructions/golang.instructions.md
|
- .github/instructions/golang.instructions.md
|
||||||
deployed_file_hashes:
|
deployed_file_hashes:
|
||||||
.claude/rules/golang.md: sha256:6ebdb015cdee3b2b834cf794f3851d84113ee381025e5554a9fa814c1d54c4ad
|
.claude/rules/golang.md: sha256:6ebdb015cdee3b2b834cf794f3851d84113ee381025e5554a9fa814c1d54c4ad
|
||||||
.github/instructions/golang.instructions.md: sha256:1f477c4204be1cc8b704ed3cddad0d3c3f1b9d4db3270ae9787de7c975807053
|
.github/instructions/golang.instructions.md: sha256:1f477c4204be1cc8b704ed3cddad0d3c3f1b9d4db3270ae9787de7c975807053
|
||||||
content_hash: sha256:cc899928ca2b32bcb7b5d59e8d151e430bc388d244261c97794e1b262dd5f320
|
content_hash: sha256:3ea7e0cefb98f178f2552d51b14906d4bac9028c42467b70f22d2ecbee08015e
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic-markdown
|
name: agentic-markdown
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
virtual_path: instructions/markdown.instructions.md
|
virtual_path: instructions/markdown.instructions.md
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
package_type: apm_package
|
|
||||||
deployed_files:
|
deployed_files:
|
||||||
- .claude/rules/markdown.md
|
- .claude/rules/markdown.md
|
||||||
- .github/instructions/markdown.instructions.md
|
- .github/instructions/markdown.instructions.md
|
||||||
deployed_file_hashes:
|
deployed_file_hashes:
|
||||||
.claude/rules/markdown.md: sha256:223315c67ebf00bfb7ae7a0d288f1991a3ae8f736b8b2b0fd8468a5104b47893
|
.claude/rules/markdown.md: sha256:223315c67ebf00bfb7ae7a0d288f1991a3ae8f736b8b2b0fd8468a5104b47893
|
||||||
.github/instructions/markdown.instructions.md: sha256:91d656b4d6c90a8ae10ca520e2f5c9444a4b6add5520328f24ad2a919e0f4747
|
.github/instructions/markdown.instructions.md: sha256:91d656b4d6c90a8ae10ca520e2f5c9444a4b6add5520328f24ad2a919e0f4747
|
||||||
content_hash: sha256:1862a115c834b4b8f4d9e036c2f05fa934304f3f3f1b20e235da515b8f0dc44b
|
content_hash: sha256:95283b86401c5cc052eaaa4e9f71b34a673f1e1f311a70ed93937d4deba2d272
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic-powershell
|
name: agentic-powershell
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
virtual_path: instructions/powershell.instructions.md
|
virtual_path: instructions/powershell.instructions.md
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
package_type: apm_package
|
|
||||||
deployed_files:
|
deployed_files:
|
||||||
- .claude/rules/powershell.md
|
- .claude/rules/powershell.md
|
||||||
- .github/instructions/powershell.instructions.md
|
- .github/instructions/powershell.instructions.md
|
||||||
deployed_file_hashes:
|
deployed_file_hashes:
|
||||||
.claude/rules/powershell.md: sha256:f17d5edda5ecc2aac8c86a32c03d32c8eccf0d945983ee70b404062d61f10a27
|
.claude/rules/powershell.md: sha256:f17d5edda5ecc2aac8c86a32c03d32c8eccf0d945983ee70b404062d61f10a27
|
||||||
.github/instructions/powershell.instructions.md: sha256:ae92d1111d4183847df527525c73d706fa1ef003d515964270f858eecf659449
|
.github/instructions/powershell.instructions.md: sha256:ae92d1111d4183847df527525c73d706fa1ef003d515964270f858eecf659449
|
||||||
content_hash: sha256:f159d7b75e7ecf3fa2c0cdf1d568799558320e06bcba5263c05e28487db68e5c
|
content_hash: sha256:b64a000548bd18ac79d7d5f5afbefaec3bb94b31765470a87a2e1ab5bb0749dd
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: code-changes
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/code-changes
|
virtual_path: skills/code-changes
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -126,9 +123,9 @@ dependencies:
|
|||||||
.claude/skills/code-changes/references/verify.md: sha256:347c831be88cf73e706717f667cc83c1cbd8867d886fecf8ed3bcd24cf69fff6
|
.claude/skills/code-changes/references/verify.md: sha256:347c831be88cf73e706717f667cc83c1cbd8867d886fecf8ed3bcd24cf69fff6
|
||||||
content_hash: sha256:8ff991b546b12798f194525ad6af84fd837614a2e6afe14ff62de3118c24c087
|
content_hash: sha256:8ff991b546b12798f194525ad6af84fd837614a2e6afe14ff62de3118c24c087
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: conventional-commit
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/conventional-commit
|
virtual_path: skills/conventional-commit
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -143,9 +140,9 @@ dependencies:
|
|||||||
.claude/skills/conventional-commit/SKILL.md: sha256:05f6b10c1909b9975410639901c713359e94d358b7b7dbc1e606d5356846d229
|
.claude/skills/conventional-commit/SKILL.md: sha256:05f6b10c1909b9975410639901c713359e94d358b7b7dbc1e606d5356846d229
|
||||||
content_hash: sha256:44bd33d20c6122489d0eedaa292dcf9b155439d021661e7ae84ce9b6f812d363
|
content_hash: sha256:44bd33d20c6122489d0eedaa292dcf9b155439d021661e7ae84ce9b6f812d363
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: golang
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/golang
|
virtual_path: skills/golang
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -160,9 +157,9 @@ dependencies:
|
|||||||
.claude/skills/golang/SKILL.md: sha256:97481de42769712647f968ac99e99375df242c90c051b13aecb6b946e381370b
|
.claude/skills/golang/SKILL.md: sha256:97481de42769712647f968ac99e99375df242c90c051b13aecb6b946e381370b
|
||||||
content_hash: sha256:0b6572070aff3e4c6b61f6d9b5cf844756676d4a9669c16544f28e911eafc224
|
content_hash: sha256:0b6572070aff3e4c6b61f6d9b5cf844756676d4a9669c16544f28e911eafc224
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: markdown
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/markdown
|
virtual_path: skills/markdown
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -177,9 +174,9 @@ dependencies:
|
|||||||
.claude/skills/markdown/SKILL.md: sha256:841c2953f949e0e5a1641e895a88f8e9ab4b7e7fab6824728cc22fbdcaba4d8d
|
.claude/skills/markdown/SKILL.md: sha256:841c2953f949e0e5a1641e895a88f8e9ab4b7e7fab6824728cc22fbdcaba4d8d
|
||||||
content_hash: sha256:fa25f4f36faa33fa51ec6e9a3b5bf7cde618d8d7dfb572dd8f55733dc1813265
|
content_hash: sha256:fa25f4f36faa33fa51ec6e9a3b5bf7cde618d8d7dfb572dd8f55733dc1813265
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: powershell
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/powershell
|
virtual_path: skills/powershell
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -194,9 +191,9 @@ dependencies:
|
|||||||
.claude/skills/powershell/SKILL.md: sha256:cedf9f49815cf9d78bcad7907b835707d037960e71e7481081771c086d346692
|
.claude/skills/powershell/SKILL.md: sha256:cedf9f49815cf9d78bcad7907b835707d037960e71e7481081771c086d346692
|
||||||
content_hash: sha256:bc844acc1cf9ccc5d2d10e1c889b8b5b69b92f743e3bc11e0bc9a386770fc864
|
content_hash: sha256:bc844acc1cf9ccc5d2d10e1c889b8b5b69b92f743e3bc11e0bc9a386770fc864
|
||||||
- repo_url: jandedobbeleer/agentic
|
- repo_url: jandedobbeleer/agentic
|
||||||
name: agentic
|
name: writing-clearly-and-concisely
|
||||||
host: github.com
|
host: github.com
|
||||||
resolved_commit: a8a75d7320a35f2502011817e18c8597977c37c9
|
resolved_commit: 856a1f17ca750b4266e509c32873f8c89c70c369
|
||||||
version: unknown
|
version: unknown
|
||||||
virtual_path: skills/writing-clearly-and-concisely
|
virtual_path: skills/writing-clearly-and-concisely
|
||||||
is_virtual: true
|
is_virtual: true
|
||||||
@@ -239,294 +236,6 @@ dependencies:
|
|||||||
.claude/skills/writing-clearly-and-concisely/signs-of-ai-writing.md: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
.claude/skills/writing-clearly-and-concisely/signs-of-ai-writing.md: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
||||||
content_hash: sha256:f2651cddb46c9695f38a30a75e9c247c41518a9d47f63256f6cafafe94d2a1ff
|
content_hash: sha256:f2651cddb46c9695f38a30a75e9c247c41518a9d47f63256f6cafafe94d2a1ff
|
||||||
deployments:
|
deployments:
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/ast-grep
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/ast-grep/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
content_hash: sha256:1d356580b6d3af4feb5722e820b1c34041f6e90162c063f1c63fce3f21c72543
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/ast-grep/references/rule_reference.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
|
||||||
content_hash: sha256:9f6d2ba2f2dbde059f61f426c262abe943f548984496962c43c7cc6e44813ad6
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:392079734548467ac5ea00c20ecfd8e7bd431a5a3377afbd8e06d642eeac4e91
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/analyze.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:0a1e4825d315f44f58f13851716b42a9a6a54f6b7a6b17aa101b97d3d1fde75b
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/delegate.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:3bbb47460f76ce9568f6eea07091f981b6127dda6ff7545456b2abd3a9b9ef72
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/deliver.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:f4c48a1adf3139ddb9259339c2919e533ee448b1a1e9b03a1393fc38ebebf0e4
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/escalate.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:b240512bcc3764ee82fbf880c11d74f4b73e4bee640e64d55ad62fea70484874
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/issue-triage.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:7e92dad2274802263787f22f80ca5dcf2a2614fd4460650b19cfc5ec904169c2
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/model-tiers.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:fa3e9a6ce99f9f21fbb2c525428960411fb344dc75d3fde1bf5297927d5961aa
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/plan.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:d1bdd255c147cd3ea4aaadcbb0d6380c6753af930f23401a4be4473d17b4c165
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/pr-review-comments.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:ff3d4be9488c4363b55947ddea07dc350e52d26fe656b4155b5a621cdb37a1c9
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/supervise.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:579ea976220ed6c3a1ed92983985aa1e78a8adae54a59845eb21481a4910d67e
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/code-changes/references/verify.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/code-changes
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/code-changes
|
|
||||||
content_hash: sha256:347c831be88cf73e706717f667cc83c1cbd8867d886fecf8ed3bcd24cf69fff6
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/conventional-commit
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/conventional-commit
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/conventional-commit
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/conventional-commit/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/conventional-commit
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/conventional-commit
|
|
||||||
content_hash: sha256:05f6b10c1909b9975410639901c713359e94d358b7b7dbc1e606d5356846d229
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/golang
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/golang
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/golang
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/golang/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/golang
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/golang
|
|
||||||
content_hash: sha256:97481de42769712647f968ac99e99375df242c90c051b13aecb6b946e381370b
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/markdown
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/markdown
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/markdown
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/markdown/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/markdown
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/markdown
|
|
||||||
content_hash: sha256:841c2953f949e0e5a1641e895a88f8e9ab4b7e7fab6824728cc22fbdcaba4d8d
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/powershell
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/powershell
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/powershell
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/powershell/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/powershell
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/powershell
|
|
||||||
content_hash: sha256:cedf9f49815cf9d78bcad7907b835707d037960e71e7481081771c086d346692
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: null
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/README.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:cd8241146abf3e7514fdb07a6db2e06c8535a4f78dd1ab471901b2e7fe4db089
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/SKILL.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:d2b345fcfc61e8143136e27b1ca2db9585c5fc46c63f0abd89a8547391349c36
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/01-introductory.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:248b18596fa18cf63605182688565d25d115c859f602068185f6014c26addbfe
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:8cead3fc56b54ab5fc22e52c14423182fdce2d9535d4c1dda1f8319cac542027
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:3867f33512ff2f0e965386dbb558579aab43ca10f070bd48d732584b9b5119e0
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:150feae0c201def056a96dd25fa5d23e015f53632b21f3bcd7b7266f8197c563
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:60db286f5166b1b6f4d85a0cc39471b375fbd62d6057d3844533551fb09f2c2d
|
|
||||||
- kind: project-relative
|
|
||||||
target: agents
|
|
||||||
value: .agents/skills/writing-clearly-and-concisely/signs-of-ai-writing.md
|
|
||||||
runtime: null
|
|
||||||
scope: project
|
|
||||||
owners:
|
|
||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
|
||||||
content_hash: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
|
||||||
- kind: project-relative
|
- kind: project-relative
|
||||||
target: claude
|
target: claude
|
||||||
value: .claude/rules/golang.md
|
value: .claude/rules/golang.md
|
||||||
@@ -842,6 +551,294 @@ deployments:
|
|||||||
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
content_hash: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
content_hash: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/ast-grep
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/ast-grep/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
content_hash: sha256:1d356580b6d3af4feb5722e820b1c34041f6e90162c063f1c63fce3f21c72543
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/ast-grep/references/rule_reference.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
active_owner: ast-grep/agent-skill/ast-grep/skills/ast-grep
|
||||||
|
content_hash: sha256:9f6d2ba2f2dbde059f61f426c262abe943f548984496962c43c7cc6e44813ad6
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:392079734548467ac5ea00c20ecfd8e7bd431a5a3377afbd8e06d642eeac4e91
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/analyze.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:0a1e4825d315f44f58f13851716b42a9a6a54f6b7a6b17aa101b97d3d1fde75b
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/delegate.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:3bbb47460f76ce9568f6eea07091f981b6127dda6ff7545456b2abd3a9b9ef72
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/deliver.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:f4c48a1adf3139ddb9259339c2919e533ee448b1a1e9b03a1393fc38ebebf0e4
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/escalate.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:b240512bcc3764ee82fbf880c11d74f4b73e4bee640e64d55ad62fea70484874
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/issue-triage.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:7e92dad2274802263787f22f80ca5dcf2a2614fd4460650b19cfc5ec904169c2
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/model-tiers.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:fa3e9a6ce99f9f21fbb2c525428960411fb344dc75d3fde1bf5297927d5961aa
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/plan.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:d1bdd255c147cd3ea4aaadcbb0d6380c6753af930f23401a4be4473d17b4c165
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/pr-review-comments.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:ff3d4be9488c4363b55947ddea07dc350e52d26fe656b4155b5a621cdb37a1c9
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/supervise.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:579ea976220ed6c3a1ed92983985aa1e78a8adae54a59845eb21481a4910d67e
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/code-changes/references/verify.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/code-changes
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/code-changes
|
||||||
|
content_hash: sha256:347c831be88cf73e706717f667cc83c1cbd8867d886fecf8ed3bcd24cf69fff6
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/conventional-commit
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/conventional-commit
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/conventional-commit
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/conventional-commit/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/conventional-commit
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/conventional-commit
|
||||||
|
content_hash: sha256:05f6b10c1909b9975410639901c713359e94d358b7b7dbc1e606d5356846d229
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/golang
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/golang
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/golang
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/golang/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/golang
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/golang
|
||||||
|
content_hash: sha256:97481de42769712647f968ac99e99375df242c90c051b13aecb6b946e381370b
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/markdown
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/markdown
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/markdown
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/markdown/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/markdown
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/markdown
|
||||||
|
content_hash: sha256:841c2953f949e0e5a1641e895a88f8e9ab4b7e7fab6824728cc22fbdcaba4d8d
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/powershell
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/powershell
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/powershell
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/powershell/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/powershell
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/powershell
|
||||||
|
content_hash: sha256:cedf9f49815cf9d78bcad7907b835707d037960e71e7481081771c086d346692
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: null
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/README.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:cd8241146abf3e7514fdb07a6db2e06c8535a4f78dd1ab471901b2e7fe4db089
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/SKILL.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:d2b345fcfc61e8143136e27b1ca2db9585c5fc46c63f0abd89a8547391349c36
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/01-introductory.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:248b18596fa18cf63605182688565d25d115c859f602068185f6014c26addbfe
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/02-elementary-rules-of-usage.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:8cead3fc56b54ab5fc22e52c14423182fdce2d9535d4c1dda1f8319cac542027
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/03-elementary-principles-of-composition.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:3867f33512ff2f0e965386dbb558579aab43ca10f070bd48d732584b9b5119e0
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/04-a-few-matters-of-form.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:150feae0c201def056a96dd25fa5d23e015f53632b21f3bcd7b7266f8197c563
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/elements-of-style/05-words-and-expressions-commonly-misused.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:60db286f5166b1b6f4d85a0cc39471b375fbd62d6057d3844533551fb09f2c2d
|
||||||
|
- kind: project-relative
|
||||||
|
target: copilot
|
||||||
|
value: .agents/skills/writing-clearly-and-concisely/signs-of-ai-writing.md
|
||||||
|
runtime: null
|
||||||
|
scope: project
|
||||||
|
owners:
|
||||||
|
- jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
active_owner: jandedobbeleer/agentic/skills/writing-clearly-and-concisely
|
||||||
|
content_hash: sha256:06d135c200e1bbfdbe90f433dfbdffeb9c4ea07f028a9a880f4026622e5c10fd
|
||||||
- kind: project-relative
|
- kind: project-relative
|
||||||
target: copilot
|
target: copilot
|
||||||
value: .github/instructions/golang.instructions.md
|
value: .github/instructions/golang.instructions.md
|
||||||
|
|||||||
Reference in New Issue
Block a user