diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index 66a812e..b0cad06 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -83,9 +83,9 @@ Categorize every finding: ## Rules -1. Always review the tests first — they reveal intent and coverage +1. Review the tests first — they reveal intent and coverage 2. Read the spec or task description before reviewing code -3. Every Critical and Important finding must include a specific fix recommendation -4. Never approve code with Critical issues -5. Always acknowledge what's done well — specific praise motivates good practices +3. Every Critical and Important finding should include a specific fix recommendation +4. Don't approve code with Critical issues +5. Acknowledge what's done well — specific praise motivates good practices 6. If you're uncertain about something, say so and suggest investigation rather than guessing diff --git a/agents/test-engineer.md b/agents/test-engineer.md index 2289bac..d63e71e 100644 --- a/agents/test-engineer.md +++ b/agents/test-engineer.md @@ -25,7 +25,7 @@ Crosses a boundary → Integration test Critical user flow → E2E test ``` -Always test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover. +Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover. ### 3. Follow the Prove-It Pattern for Bugs diff --git a/skills/api-and-interface-design/SKILL.md b/skills/api-and-interface-design/SKILL.md index d7b7c22..4c65069 100644 --- a/skills/api-and-interface-design/SKILL.md +++ b/skills/api-and-interface-design/SKILL.md @@ -32,7 +32,7 @@ This means: every public behavior — including undocumented quirks, error messa ### The One-Version Rule -Never force consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork. +Avoid forcing consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork. ### 1. Contract First @@ -170,7 +170,7 @@ POST /api/tasks/:id/comments → Add a comment to a task ### Pagination -Always paginate list endpoints: +Paginate list endpoints: ```typescript // Request diff --git a/skills/code-review-and-quality/SKILL.md b/skills/code-review-and-quality/SKILL.md index 838e52f..83c82dd 100644 --- a/skills/code-review-and-quality/SKILL.md +++ b/skills/code-review-and-quality/SKILL.md @@ -103,7 +103,7 @@ Small, focused changes are easier to review, faster to merge, and safer to deplo **When large changes are acceptable:** Complete file deletions and automated refactoring where the reviewer only needs to verify intent, not every line. -**Always separate refactoring from feature work.** A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion. +**Separate refactoring from feature work.** A change that refactors existing code and adds new behavior is two changes — submit them separately. Small cleanups (variable renaming) can be included at reviewer discretion. ## Change Descriptions @@ -240,7 +240,7 @@ When resolving review disputes, apply this hierarchy: 3. **Software design** must be evaluated on engineering principles, not personal preference 4. **Codebase consistency** is acceptable if it doesn't degrade overall health -**Never accept "I'll clean it up later."** Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment. +**Don't accept "I'll clean it up later."** Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it's a genuine emergency. If surrounding issues can't be addressed in this change, require filing a bug with self-assignment. ## Honesty in Review diff --git a/skills/code-simplification/SKILL.md b/skills/code-simplification/SKILL.md index 6500a90..66a8417 100644 --- a/skills/code-simplification/SKILL.md +++ b/skills/code-simplification/SKILL.md @@ -31,7 +31,7 @@ Simplify code by reducing complexity while preserving exact behavior. The goal i ### 1. Preserve Behavior Exactly -Never change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it. +Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it. ``` ASK BEFORE EVERY CHANGE: @@ -156,7 +156,7 @@ Scan for these patterns — each one is a concrete signal, not a vague smell: ### Step 3: Apply Changes Incrementally -Make one simplification at a time. Run tests after each change. **Always submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them. +Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them. ``` FOR EACH SIMPLIFICATION: @@ -166,7 +166,7 @@ FOR EACH SIMPLIFICATION: 4. If tests fail → revert and reconsider ``` -Never batch multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it. +Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it. **The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review. diff --git a/skills/context-engineering/SKILL.md b/skills/context-engineering/SKILL.md index 8f9513e..ae7ca1c 100644 --- a/skills/context-engineering/SKILL.md +++ b/skills/context-engineering/SKILL.md @@ -221,7 +221,7 @@ If the spec doesn't cover a case you need to implement: 1. Check existing code for precedent 2. If no precedent exists, **stop and ask** -3. Never invent requirements — that's the human's job +3. Don't invent requirements — that's the human's job ``` MISSING REQUIREMENT: @@ -257,7 +257,7 @@ This catches wrong directions before you've built on them. It's a 30-second inve | Context starvation | Agent invents APIs, ignores conventions | Load rules file + relevant source files before each task | | Context flooding | Agent loses focus when loaded with >5,000 lines of non-task-specific context. More files does not mean better output. | Include only what is relevant to the current task. Aim for <2,000 lines of focused context per task. | | Stale context | Agent references outdated patterns or deleted code | Start fresh sessions when context drifts | -| Missing examples | Agent invents a new style instead of following yours | Always include one example of the pattern to follow | +| Missing examples | Agent invents a new style instead of following yours | Include one example of the pattern to follow | | Implicit knowledge | Agent doesn't know project-specific rules | Write it down in rules files — if it's not written, it doesn't exist | | Silent confusion | Agent guesses when it should ask | Surface ambiguity explicitly using the confusion management patterns above | diff --git a/skills/debugging-and-error-recovery/SKILL.md b/skills/debugging-and-error-recovery/SKILL.md index 2286b40..9a4311f 100644 --- a/skills/debugging-and-error-recovery/SKILL.md +++ b/skills/debugging-and-error-recovery/SKILL.md @@ -31,7 +31,7 @@ When anything unexpected happens: 6. RESUME only after verification passes ``` -**Never push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-10 wrong. +**Don't push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-10 wrong. ## The Triage Checklist diff --git a/skills/deprecation-and-migration/SKILL.md b/skills/deprecation-and-migration/SKILL.md index dc49aca..ab1c17c 100644 --- a/skills/deprecation-and-migration/SKILL.md +++ b/skills/deprecation-and-migration/SKILL.md @@ -46,7 +46,7 @@ Before deprecating anything, answer these questions: → Quantify the migration scope. 3. Does a replacement exist? - → If no, build the replacement first. Never deprecate without an alternative. + → If no, build the replacement first. Don't deprecate without an alternative. 4. What's the migration cost for each consumer? → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost. @@ -68,7 +68,7 @@ Before deprecating anything, answer these questions: ### Step 1: Build the Replacement -Never deprecate without a working alternative. The replacement must: +Don't deprecate without a working alternative. The replacement must: - Cover all critical use cases of the old system - Have documentation and migration guides diff --git a/skills/documentation-and-adrs/SKILL.md b/skills/documentation-and-adrs/SKILL.md index 5cc94ea..1d7686b 100644 --- a/skills/documentation-and-adrs/SKILL.md +++ b/skills/documentation-and-adrs/SKILL.md @@ -86,7 +86,7 @@ Use PostgreSQL with Prisma ORM. PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED) ``` -- **Never delete old ADRs.** They capture historical context. +- **Don't delete old ADRs.** They capture historical context. - When a decision changes, write a new ADR that references and supersedes the old one. ## Inline Documentation diff --git a/skills/git-workflow-and-versioning/SKILL.md b/skills/git-workflow-and-versioning/SKILL.md index 681cdac..536effa 100644 --- a/skills/git-workflow-and-versioning/SKILL.md +++ b/skills/git-workflow-and-versioning/SKILL.md @@ -15,7 +15,7 @@ Always. Every code change flows through git. ## Core Principles -### Trunk-Based Development +### Trunk-Based Development (Recommended) Keep `main` always deployable. Work in short-lived feature branches that merge back within 1-3 days. Long-lived development branches are hidden costs — they diverge, create merge conflicts, and delay integration. DORA research consistently shows trunk-based development correlates with high-performing engineering teams. @@ -25,9 +25,11 @@ main ──●──●──●──●──●──●──●──●─ ●──●─╱ ●──╱ ← short-lived feature branches (1-3 days) ``` +This is the recommended default. Teams using gitflow or long-lived branches can adapt the principles (atomic commits, small changes, descriptive messages) to their branching model — the commit discipline matters more than the specific branching strategy. + - **Dev branches are costs.** Every day a branch lives, it accumulates merge risk. - **Release branches are acceptable.** When you need to stabilize a release while main moves forward. -- **Feature flags > long branches.** Deploy incomplete work behind flags rather than keeping it on a branch for weeks. +- **Feature flags > long branches.** Prefer deploying incomplete work behind flags rather than keeping it on a branch for weeks. ### 1. Commit Early, Commit Often @@ -91,7 +93,7 @@ update auth.ts - `docs` — Documentation only - `chore` — Tooling, dependencies, config -### 4. Never Mix Concerns +### 4. Keep Concerns Separate Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit — and ideally a separate PR: @@ -104,7 +106,7 @@ git commit -m "feat: add phone number validation to registration" git commit -m "refactor validation and add phone number field" ``` -**Always separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion. +**Separate refactoring from feature work.** A refactoring change and a feature change are two different changes — submit them separately. This makes each change easier to review, revert, and understand in history. Small cleanups (renaming a variable) can be included in a feature commit at reviewer discretion. ### 5. Size Your Changes @@ -243,7 +245,7 @@ Automate this with git hooks: - **Commit generated files** only if the project expects them (e.g., `package-lock.json`, Prisma migrations) - **Don't commit** build output (`dist/`, `.next/`), environment files (`.env`), or IDE config (`.vscode/settings.json` unless shared) -- **Always have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem` +- **Have a `.gitignore`** that covers: `node_modules/`, `dist/`, `.env`, `.env.local`, `*.pem` ## Using Git for Debugging diff --git a/skills/incremental-implementation/SKILL.md b/skills/incremental-implementation/SKILL.md index b07f97a..0a64135 100644 --- a/skills/incremental-implementation/SKILL.md +++ b/skills/incremental-implementation/SKILL.md @@ -7,7 +7,7 @@ description: Use when implementing any feature or change that touches more than ## Overview -Build in thin vertical slices — implement one piece, test it, verify it, then expand. Never attempt to implement an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable. +Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable. ## When to Use @@ -140,9 +140,9 @@ Each increment changes one logical thing. Don't mix concerns: **Good:** Three separate commits — one for each change. -### Rule 2: Always Compilable +### Rule 2: Keep It Compilable -After each increment, the project must build and existing tests must pass. Never leave the codebase in a broken state between slices. +After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices. ### Rule 3: Feature Flags for Incomplete Features @@ -178,7 +178,7 @@ Each increment should be independently revertable: - Additive changes (new files, new functions) are easy to revert - Modifications to existing code should be minimal and focused - Database migrations should have corresponding rollback migrations -- Never delete something in one commit and replace it in the same commit — separate them +- Avoid deleting something in one commit and replacing it in the same commit — separate them ## Working with Agents diff --git a/skills/spec-driven-development/SKILL.md b/skills/spec-driven-development/SKILL.md index 804cf76..6d9a369 100644 --- a/skills/spec-driven-development/SKILL.md +++ b/skills/spec-driven-development/SKILL.md @@ -46,7 +46,7 @@ ASSUMPTIONS I'M MAKING: → Correct me now or I'll proceed with these. ``` -Never silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding. +Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding. **Write a spec document covering these six core areas:** diff --git a/skills/using-agent-skills/SKILL.md b/skills/using-agent-skills/SKILL.md index d6836a5..a50785a 100644 --- a/skills/using-agent-skills/SKILL.md +++ b/skills/using-agent-skills/SKILL.md @@ -51,7 +51,7 @@ ASSUMPTIONS I'M MAKING: → Correct me now or I'll proceed with these. ``` -Never silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework. +Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework. ### 2. Manage Confusion Actively @@ -121,7 +121,7 @@ These are the subtle errors that look like productivity but create problems: ## Skill Rules -1. **Always check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes. +1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes. 2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.