@ecc-hgy/ae 0.5.0 → 0.6.0

package/skills/review/SKILL.md

@@ -1,119 +1,119 @@
----
-name: review
-description: Two-axis review (Standards / Spec) of the changes for a need that is about to close, followed by sedimentation routing - review findings flow into prd.md / design.md / spec/ADR/ / S2 candidates per `spec/AGENTS.md`. Used at S1 node B7.
----
-
-# Review
-
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
-
-- **Standards** - does the code conform to this repo's documented coding standards?
-- **Spec** - does the code faithfully implement the originating need?
-
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
-
-## Entry (S1 node B7)
-
-Invoke this skill when a need is about to close - typically after B6 user re-verification passes. Inputs:
-
-- The owning need: `spec/needs/<need-name>/` (must contain `prd.md`, `design.md`, `todo.md`, and at least one `issues/*.md` if this close was preceded by a B-loop)
-- The fixed point: the git commit at which work on this need started (merge-base with `main`, or the user's specified SHA)
-- `spec/INDEX.md` (to confirm the need-name and to update afterward)
-
-## Process
-
-### 1. Pin the fixed point
-
-Whatever the user said is the fixed point - a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what - a branch, a commit, or `main`?" Don't proceed until you have it.
-
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
-
-### 2. Identify the spec source
-
-The spec is fixed by the need-name (resolved from the user's input, the active branch, or `spec/INDEX.md`'s `当前节点` column). Read these files in order:
-
-1. `spec/needs/<need-name>/prd.md` - WHAT and WHY (acceptance criteria)
-2. `spec/needs/<need-name>/design.md` - HOW (decisions and trade-offs)
-3. `spec/needs/<need-name>/todo.md` - execution checklist (rolling)
-4. `spec/needs/<need-name>/issues/*.md` - any B-loop issue files for this close
-
-Do NOT search `docs/`, `specs/`, `.scratch/`, or commit-message issue references - the contract is: this project always uses `spec/needs/<need-name>/`. If `<need-name>` cannot be determined, STOP and ask the user.
-
-### 3. Identify the standards sources
-
-Anything in the repo that documents how code should be written. For this project's spec layout, the canonical sources are:
-
-- `AGENTS.md`, `CLAUDE.md` (entry rules + R1 - mirrored content)
-- `spec/README.md` (project map; rarely contains rules but read for context)
-- `spec/INDEX.md` (need + ADR index; the `当前节点` and `related-needs` columns reveal cross-need coupling)
-- `spec/ADR/*.md` (architectural decisions are standards; treat `status: accepted` as binding)
-- `CONTRIBUTING.md` (if present at repo root)
-- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json`, `ruff.toml`, etc. (machine-enforced - note them but don't re-check what tooling already checks)
-- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md` at the repo root or under `spec/`
-
-Do NOT look under `docs/adr/`, `CONTEXT.md`, or `CONTEXT-MAP.md` - this project uses `spec/ADR/` and the INDEX/README split instead.
-
-Collect the list of files. The **Standards** sub-agent will read them.
-
-### 4. Spawn both sub-agents in parallel
-
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
-
-**Standards sub-agent prompt** - include:
-
-- The full diff command and commit list.
-- The list of standards-source files you found in step 3.
-- The brief: "Read the standards docs. Then read the diff. Report - per file/hunk where relevant - every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
-
-**Spec sub-agent prompt** - include:
-
-- The diff command and commit list.
-- The path or fetched contents of the spec.
-- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
-
-If the spec is missing, skip the Spec sub-agent and note this in the final report.
-
-### 5. Aggregate
-
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings - the two axes are deliberately separate so the user can see them independently.
-
-End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged.
-
-### 6. Sediment (sedimentation routing)
-
-This step is what makes review a B7 skill and not a generic PR review. After Aggregate, walk through every finding from BOTH axes and route each one of four ways. Show the user a routing plan; only execute after approval.
-
-| Finding type | Routing target | What to write |
-|---|---|---|
-| **Business rule** (spec said WHAT was wrong, or B-loop surfaced an unstated rule) | `spec/needs/<need-name>/prd.md` | Patch the relevant section; bump `last-aligned: <today>`; keep `status: active` |
-| **Local technical decision** (affects ONLY this need) | `spec/needs/<need-name>/design.md` | Patch the relevant section; bump `last-aligned`; keep `status: active` |
-| **Cross-need decision** (affects 2+ needs, or a project-wide invariant) | New `spec/ADR/NNNN-<title>.md` | New ADR with `status: proposed` (NOT accepted - user decides in a separate pass). In affected `design.md` files, add a reference and prune the local version of the decision. |
-| **Reusable method / pattern** (not project-specific knowledge) | Handoff proposal (NOT this skill) | Add a single line under "S2 candidates" in `handoff.md` (or surface it for the next `handoff` skill run). Do NOT create a skill file here - promotion is user-confirmed at S2. |
-
-After routing:
-
-1. Update `spec/INDEX.md`:
-   - Set every `issues/*.md` referenced in this close to "已验收"
-   - If any `prd.md` / `design.md` was patched, leave `status: active` and refresh `last-aligned`
-   - If a new ADR was created, add a row under `## ADR` with `status: proposed`
-   - If unsure, run `ae index-rebuild`
-2. Print a one-block summary to the user:
-   - Findings routed to prd / design / ADR / S2-candidates with counts
-   - Files modified (path list)
-   - Suggested next action: close the need (mark all relevant files appropriately) or open a fresh A1 alignment for the new ADR proposals
-
-## Boundaries
-
-- This skill READS the diff and need files, WRITES patches to `prd.md` / `design.md`, NEW files in `spec/ADR/`, and ONE INDEX update.
-- It does NOT close or archive `prd.md` / `design.md` - `archived` is reserved for need-level lifecycle, not B7.
-- It does NOT promote rules into reusable skills - S2 promotion is user-confirmed in a separate pass.
-- It does NOT invoke `improve-codebase-architecture` directly - that skill is user-triggered; B7 findings can list it as a suggested follow-up but do not call it.
-
-## Why two axes
-
-A change can pass one axis and fail the other:
-
-- Code that follows every standard but implements the wrong thing -> **Standards pass, Spec fail.**
-- Code that does exactly what the issue asked but breaks the project's conventions -> **Spec pass, Standards fail.**
-
-Reporting them separately stops one axis from masking the other.
+---
+name: review
+description: Two-axis review (Standards / Spec) of the changes for a need that is about to close, followed by sedimentation routing - review findings flow into prd.md / design.md / spec/ADR/ / S2 candidates per `spec/AGENTS.md`. Used at S1 node B7.
+---
+
+# Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** - does the code conform to this repo's documented coding standards?
+- **Spec** - does the code faithfully implement the originating need?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+## Entry (S1 node B7)
+
+Invoke this skill when a need is about to close - typically after B6 user re-verification passes. Inputs:
+
+- The owning need: `spec/needs/<need-name>/` (must contain `prd.md`, `design.md`, `todo.md`, and at least one `issues/*.md` if this close was preceded by a B-loop)
+- The fixed point: the git commit at which work on this need started (merge-base with `main`, or the user's specified SHA)
+- `spec/INDEX.md` (to confirm the need-name and to update afterward)
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point - a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what - a branch, a commit, or `main`?" Don't proceed until you have it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+### 2. Identify the spec source
+
+The spec is fixed by the need-name (resolved from the user's input, the active branch, or `spec/INDEX.md`'s `当前节点` column). Read these files in order:
+
+1. `spec/needs/<need-name>/prd.md` - WHAT and WHY (acceptance criteria)
+2. `spec/needs/<need-name>/design.md` - HOW (decisions and trade-offs)
+3. `spec/needs/<need-name>/todo.md` - execution checklist (rolling)
+4. `spec/needs/<need-name>/issues/*.md` - any B-loop issue files for this close
+
+Do NOT search `docs/`, `specs/`, `.scratch/`, or commit-message issue references - the contract is: this project always uses `spec/needs/<need-name>/`. If `<need-name>` cannot be determined, STOP and ask the user.
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written. For this project's spec layout, the canonical sources are:
+
+- `AGENTS.md`, `CLAUDE.md` (entry rules + R1 - mirrored content)
+- `spec/README.md` (project map; rarely contains rules but read for context)
+- `spec/INDEX.md` (need + ADR index; the `当前节点` and `related-needs` columns reveal cross-need coupling)
+- `spec/ADR/*.md` (architectural decisions are standards; treat `status: accepted` as binding)
+- `CONTRIBUTING.md` (if present at repo root)
+- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json`, `ruff.toml`, etc. (machine-enforced - note them but don't re-check what tooling already checks)
+- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md` at the repo root or under `spec/`
+
+Do NOT look under `docs/adr/`, `CONTEXT.md`, or `CONTEXT-MAP.md` - this project uses `spec/ADR/` and the INDEX/README split instead.
+
+Collect the list of files. The **Standards** sub-agent will read them.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** - include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3.
+- The brief: "Read the standards docs. Then read the diff. Report - per file/hunk where relevant - every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** - include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings - the two axes are deliberately separate so the user can see them independently.
+
+End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged.
+
+### 6. Sediment (sedimentation routing)
+
+This step is what makes review a B7 skill and not a generic PR review. After Aggregate, walk through every finding from BOTH axes and route each one of four ways. Show the user a routing plan; only execute after approval.
+
+| Finding type | Routing target | What to write |
+|---|---|---|
+| **Business rule** (spec said WHAT was wrong, or B-loop surfaced an unstated rule) | `spec/needs/<need-name>/prd.md` | Patch the relevant section; bump `last-aligned: <today>`; keep `status: active` |
+| **Local technical decision** (affects ONLY this need) | `spec/needs/<need-name>/design.md` | Patch the relevant section; bump `last-aligned`; keep `status: active` |
+| **Cross-need decision** (affects 2+ needs, or a project-wide invariant) | New `spec/ADR/NNNN-<title>.md` | New ADR with `status: proposed` (NOT accepted - user decides in a separate pass). In affected `design.md` files, add a reference and prune the local version of the decision. |
+| **Reusable method / pattern** (not project-specific knowledge) | Handoff proposal (NOT this skill) | Add a single line under "S2 candidates" in `handoff.md` (or surface it for the next `handoff` skill run). Do NOT create a skill file here - promotion is user-confirmed at S2. |
+
+After routing:
+
+1. Update `spec/INDEX.md`:
+   - Set every `issues/*.md` referenced in this close to "已验收"
+   - If any `prd.md` / `design.md` was patched, leave `status: active` and refresh `last-aligned`
+   - If a new ADR was created, add a row under `## ADR` with `status: proposed`
+   - If unsure, run `ae index-rebuild`
+2. Print a one-block summary to the user:
+   - Findings routed to prd / design / ADR / S2-candidates with counts
+   - Files modified (path list)
+   - Suggested next action: close the need (mark all relevant files appropriately) or open a fresh A1 alignment for the new ADR proposals
+
+## Boundaries
+
+- This skill READS the diff and need files, WRITES patches to `prd.md` / `design.md`, NEW files in `spec/ADR/`, and ONE INDEX update.
+- It does NOT close or archive `prd.md` / `design.md` - `archived` is reserved for need-level lifecycle, not B7.
+- It does NOT promote rules into reusable skills - S2 promotion is user-confirmed in a separate pass.
+- It does NOT invoke `improve-codebase-architecture` directly - that skill is user-triggered; B7 findings can list it as a suggested follow-up but do not call it.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing -> **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions -> **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/skills/tdd/SKILL.md

@@ -1,157 +1,157 @@
----
-name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
----
-
-# Test-Driven Development
-
-## Inputs (S1 nodes A5 / B5)
-
-This skill operates on a single need. Read the following before starting any cycle:
-
-- `spec/needs/<need-name>/design.md` - the HOW (modules, interfaces, key trade-offs); test names and the public interfaces under test SHOULD match its vocabulary
-- `spec/needs/<need-name>/todo.md` - the rolling task list produced by A4 `to-issues`; pick the next unchecked `## 实施` item, top-down
-- `spec/INDEX.md` - domain vocabulary; cross-need ADRs at `spec/ADR/`
-
-## Hard Constraints
-
-- **No scope smuggling.** Do NOT implement anything not present in `design.md`. If the current `todo.md` item requires behavior the design did not anticipate, STOP, go back to A3 (`writing-plans`) to patch `design.md`, then resume here.
-- **One slice at a time.** Pick a single `- [ ]` item from `## 实施`, complete the full red -> green -> refactor cycle for it, mark it `- [x]`, then move to the next. Do not batch.
-- **End-to-end verification is A6's job, not A5's.** This skill's exit criterion is "all `## 实施` items checked + tests green at the slice seam". Real-user-path verification happens in A6 `verification-before-completion`.
-
-## Two Modes
-
-| Mode | When | Output |
-|------|------|--------|
-| **A5 (development)** | Driven by `todo.md` after a fresh need passes A4 | Roll `todo.md` forward; mark items `- [x]` as each cycle completes |
-| **B5 (fix)** | Driven by an existing `spec/needs/<need-name>/issues/<topic>.md` after B3 diagnose | Apply the fix per the root cause; `todo.md` is NOT touched (it was already fully checked when the bug surfaced). Append progress notes to the issue file's `## bug` section instead. |
-
-## Philosophy
-
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
-
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
-
-**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
-
-See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
-
-## Anti-Pattern: Horizontal Slices
-
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
-
-This produces **crap tests**:
-
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
-- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
-- You outrun your headlights, committing to test structure before understanding the implementation
-
-**Correct approach**: Vertical slices via tracer bullets. One test -> one implementation -> repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
-
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
-
-RIGHT (vertical):
-  RED->GREEN: test1->impl1
-  RED->GREEN: test2->impl2
-  RED->GREEN: test3->impl3
-  ...
-```
-
-## Workflow
-
-### 1. Planning
-
-When exploring the codebase, use vocabulary from `spec/INDEX.md` and the current need's `design.md` so that test names and interface vocabulary match the project's language. Respect ADRs under `spec/ADR/`.
-
-Before writing any code for the current slice:
-
-- [ ] Read the `## 实施` item being implemented; confirm it traces to a section in `design.md`
-- [ ] Confirm with user (or re-read `design.md`) what interface changes the slice requires
-- [ ] Confirm which behaviors to test (prioritize per slice acceptance criteria)
-- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
-- [ ] Design interfaces for [testability](interface-design.md)
-- [ ] List the behaviors to test (not implementation steps)
-- [ ] If `design.md` needs amendment (new behavior surfaced), STOP and go back to A3
-
-Ask: "What should the public interface look like? Which behaviors are most important to test?"
-
-**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
-
-### 2. Tracer Bullet
-
-Write ONE test that confirms ONE thing about the system:
-
-```
-RED:   Write test for first behavior -> test fails
-GREEN: Write minimal code to pass -> test passes
-```
-
-This is your tracer bullet - proves the path works end-to-end.
-
-### 3. Incremental Loop
-
-For each remaining behavior:
-
-```
-RED:   Write next test -> fails
-GREEN: Minimal code to pass -> passes
-```
-
-Rules:
-
-- One test at a time
-- Only enough code to pass current test
-- Don't anticipate future tests
-- Keep tests focused on observable behavior
-
-### 4. Refactor
-
-After all tests pass, look for [refactor candidates](refactoring.md):
-
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
-
-**Never refactor while RED.** Get to GREEN first.
-
-## Checklist Per Cycle
-
-```
-[ ] Test describes behavior, not implementation
-[ ] Test uses public interface only
-[ ] Test would survive internal refactor
-[ ] Code is minimal for this test
-[ ] No speculative features added
-```
-
-## After Each Slice (A5)
-
-1. Tick the corresponding `- [ ]` -> `- [x]` in `spec/needs/<need-name>/todo.md`
-2. Update `spec/INDEX.md`:
-   - Bump the `todo` column counter (e.g. `2/8` -> `3/8`)
-   - If all `## 实施` items are now checked, set `当前节点` to `A6 verify` (per `spec/AGENTS.md` INDEX rules)
-   - If unsure, run `ae index-rebuild`
-3. Commit. Suggested message: `feat(<need-name>): T<n> <title>`.
-
-## After All Slices Checked (A5 only)
-
-Hand off to A6 `verification-before-completion` for end-to-end verification on the real user path. This skill's job ends when `todo.md` is fully checked AND slice-level tests are green.
-
-## After Fix Lands (B5 only)
-
-1. Do NOT modify `todo.md` (it was fully checked before the bug surfaced).
-2. Append a short progress note under the issue file's `## bug` section (the 7-section format produced at B4). Quote the failing test name and the root-cause one-liner.
-3. Commit. Suggested message: `fix(<need-name>): <root cause summary>`.
-4. Hand off to B6 user re-verification.
-
-## Boundaries
-
-- This skill writes code and tests, plus updates `todo.md` (A5) or the issue file's `## bug` section (B5).
-- It does NOT write `prd.md`, `design.md`, or new ADRs. Scope changes go back through A3.
-- It does NOT perform end-to-end / user-path verification - that is A6.
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Inputs (S1 nodes A5 / B5)
+
+This skill operates on a single need. Read the following before starting any cycle:
+
+- `spec/needs/<need-name>/design.md` - the HOW (modules, interfaces, key trade-offs); test names and the public interfaces under test SHOULD match its vocabulary
+- `spec/needs/<need-name>/todo.md` - the rolling task list produced by A4 `to-issues`; pick the next unchecked `## 实施` item, top-down
+- `spec/INDEX.md` - domain vocabulary; cross-need ADRs at `spec/ADR/`
+
+## Hard Constraints
+
+- **No scope smuggling.** Do NOT implement anything not present in `design.md`. If the current `todo.md` item requires behavior the design did not anticipate, STOP, go back to A3 (`writing-plans`) to patch `design.md`, then resume here.
+- **One slice at a time.** Pick a single `- [ ]` item from `## 实施`, complete the full red -> green -> refactor cycle for it, mark it `- [x]`, then move to the next. Do not batch.
+- **End-to-end verification is A6's job, not A5's.** This skill's exit criterion is "all `## 实施` items checked + tests green at the slice seam". Real-user-path verification happens in A6 `verification-before-completion`.
+
+## Two Modes
+
+| Mode | When | Output |
+|------|------|--------|
+| **A5 (development)** | Driven by `todo.md` after a fresh need passes A4 | Roll `todo.md` forward; mark items `- [x]` as each cycle completes |
+| **B5 (fix)** | Driven by an existing `spec/needs/<need-name>/issues/<topic>.md` after B3 diagnose | Apply the fix per the root cause; `todo.md` is NOT touched (it was already fully checked when the bug surfaced). Append progress notes to the issue file's `## bug` section instead. |
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test -> one implementation -> repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED->GREEN: test1->impl1
+  RED->GREEN: test2->impl2
+  RED->GREEN: test3->impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, use vocabulary from `spec/INDEX.md` and the current need's `design.md` so that test names and interface vocabulary match the project's language. Respect ADRs under `spec/ADR/`.
+
+Before writing any code for the current slice:
+
+- [ ] Read the `## 实施` item being implemented; confirm it traces to a section in `design.md`
+- [ ] Confirm with user (or re-read `design.md`) what interface changes the slice requires
+- [ ] Confirm which behaviors to test (prioritize per slice acceptance criteria)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] If `design.md` needs amendment (new behavior surfaced), STOP and go back to A3
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior -> test fails
+GREEN: Write minimal code to pass -> test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test -> fails
+GREEN: Minimal code to pass -> passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```
+
+## After Each Slice (A5)
+
+1. Tick the corresponding `- [ ]` -> `- [x]` in `spec/needs/<need-name>/todo.md`
+2. Update `spec/INDEX.md`:
+   - Bump the `todo` column counter (e.g. `2/8` -> `3/8`)
+   - If all `## 实施` items are now checked, set `当前节点` to `A6 verify` (per `spec/AGENTS.md` INDEX rules)
+   - If unsure, run `ae index-rebuild`
+3. Commit. Suggested message: `feat(<need-name>): T<n> <title>`.
+
+## After All Slices Checked (A5 only)
+
+Hand off to A6 `verification-before-completion` for end-to-end verification on the real user path. This skill's job ends when `todo.md` is fully checked AND slice-level tests are green.
+
+## After Fix Lands (B5 only)
+
+1. Do NOT modify `todo.md` (it was fully checked before the bug surfaced).
+2. Append a short progress note under the issue file's `## bug` section (the 7-section format produced at B4). Quote the failing test name and the root-cause one-liner.
+3. Commit. Suggested message: `fix(<need-name>): <root cause summary>`.
+4. Hand off to B6 user re-verification.
+
+## Boundaries
+
+- This skill writes code and tests, plus updates `todo.md` (A5) or the issue file's `## bug` section (B5).
+- It does NOT write `prd.md`, `design.md`, or new ADRs. Scope changes go back through A3.
+- It does NOT perform end-to-end / user-path verification - that is A6.

package/skills/tdd/deep-modules.md

@@ -1,33 +1,33 @@
-# Deep Modules
-
-From "A Philosophy of Software Design":
-
-**Deep module** = small interface + lots of implementation
-
-```
-┌─────────────────────┐
-│   Small Interface   │  ← Few methods, simple params
-├─────────────────────┤
-│                     │
-│                     │
-│  Deep Implementation│  ← Complex logic hidden
-│                     │
-│                     │
-└─────────────────────┘
-```
-
-**Shallow module** = large interface + little implementation (avoid)
-
-```
-┌─────────────────────────────────┐
-│       Large Interface           │  ← Many methods, complex params
-├─────────────────────────────────┤
-│  Thin Implementation            │  ← Just passes through
-└─────────────────────────────────┘
-```
-
-When designing interfaces, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?