{
  "skill_name": "planning",
  "evals": [
    {
      "id": 1,
      "prompt": "Plan a CSV export using the existing export service. Just write the plan, no interview. Include cancellation and a way to verify partial output is not presented as complete.",
      "expected_output": "Write a bounded plan from available evidence, with acceptance criteria.",
      "files": [],
      "assertions": [
        "Does not push back for an interview",
        "Names cancellation and partial-output checks",
        "Does not implement source code for a plan-only request"
      ]
    },
    {
      "id": 2,
      "prompt": "Review a plan that says proxy.ts handles authorization, while POST /api/export is excluded by its matcher. Fix the plan.",
      "expected_output": "Correct the authorization location and verification criterion.",
      "files": [],
      "assertions": [
        "Identifies the matcher-excluded path",
        "Requires authorization at the handler or data boundary",
        "Does not inflate a self-score by adding unrelated work"
      ]
    }
  ],
  "routing": {
    "should_trigger": [
      "Plan a CSV export using the existing export service. Just write the plan, no interview. Include cancellation and a way to verify partial output is not presented as complete.",
      "Review a plan that says proxy.ts handles authorization, while POST /api/export is excluded by its matcher. Fix the plan."
    ],
    "near_miss": [
      {
        "prompt": "Review the code changes on this branch without editing.",
        "expected": "pr-reviewer"
      }
    ]
  }
}

# Claim Verification

Verify claims with local evidence, not at face value. Load during plan review when a claim is locally checkable, or when the user asks to verify one.

## Contents

- When to use
- Workflow (hypothesis, evidence surface, artifacts, verdict)
- Verifying against documentation
- Output format
- Worked example: the Verify move in a review
- Integration with plan review

## When to use

- Triage (Step 2): the plan asserts something checkable about the codebase, performance, or behavior
- Dialogue (Step 3): the user responds with a specific, verifiable claim
- Standalone: the user says "verify this", "is this true", "prove it", "check this claim"
- Before relying on an assumption that drives a critical decision

## Workflow

### 1. Restate as falsifiable hypothesis

Convert the claim into a testable statement: condition, metric, threshold.

| Claim | Falsifiable hypothesis |
|-------|----------------------|
| "This function is small" | `getUser` in `src/user.ts` is under 50 lines |
| "The API is fast" | `GET /api/users` responds in under 200ms locally |
| "We have good test coverage" | `src/auth/` directory has co-located test files for >80% of modules |
| "Nobody uses this" | `legacyHelper` has zero call sites outside its own test file |
| "This is thread-safe" | Concurrent writes to `cache.ts` don't produce data races under `--race` |

If it can't be restated falsifiably (too vague or unfalsifiable), say so and skip verification.

### 2. Identify the minimal evidence surface

Choose the smallest, most direct source:

| Evidence type | Tools | When to use |
|--------------|-------|-------------|
| Code existence | `grep -r`, `find`, file reading | "Does X exist?", "Is Y used?" |
| Code metrics | `wc -l`, `tokei`, line counting | "How big is X?", "How many files?" |
| History | `git log`, `git blame`, `git shortlog` | "When was X added?", "Who wrote Y?" |
| Test output | `npm test`, `pytest`, `cargo test` | "Does X pass?", "Is Y covered?" |
| Runtime behavior | `curl`, `time`, script execution | "How fast is X?", "What does Y return?" |
| Static analysis | `tsc --noEmit`, `eslint`, `oxlint` | "Does X compile?", "Are there warnings?" |

### 3. Capture baseline artifact

Run the command and save raw output verbatim (exact command plus full output, no paraphrase). For before/after comparisons, capture the baseline first.

### 4. Capture treatment artifact (if comparing)

For change claims ("this is faster", "this reduces complexity"), capture the treatment state with the same command on the same machine.

### 5. Compare and verdict

Compare the artifacts. Three outcomes:

**VERIFIED**: evidence supports the claim within threshold.
```
Claim: "getUser is under 50 lines"
Evidence: wc -l src/user.ts → getUser function spans lines 12-38 (26 lines)
Verdict: VERIFIED, 26 lines, well under 50
```

**NOT VERIFIED**: evidence contradicts the claim.
```
Claim: "Nobody uses legacyHelper"
Evidence: grep -r "legacyHelper" src/ → 4 call sites in 3 files
Verdict: NOT VERIFIED, 4 active call sites found
```

**INCONCLUSIVE**: insufficient evidence or mixed signals.
```
Claim: "The API responds in under 200ms"
Evidence: 5 curl requests → 180ms, 210ms, 190ms, 350ms, 185ms
Verdict: INCONCLUSIVE, 3/5 under 200ms but p95 is 350ms. Depends on the threshold definition.
```

## Verifying against documentation

Some claims concern a *documented decision*, not code or runtime behavior ("the RFC says writes are idempotent", "the library supports retries natively", "the ADR rejected this approach"). Verify against the authoritative doc, not just the code.

1. **Find the authoritative source.** Closest-to-code first: ADRs/decision records, then design docs/RFCs, then official library/API docs. The user's named spec is the source of truth when one exists.
2. **Quote the relevant line.** Copy the exact sentence plus its location (file/path or doc name + section); do not paraphrase the decision.
3. **Check the doc against reality.** Docs drift. If the code contradicts the doc, that itself is the finding: report which is authoritative for this plan.
4. **Verdict.** Same three outcomes, with the citation:

```
Claim: "The payments RFC says webhook handling is idempotent"
Evidence: docs/rfc/payments.md §4: "handlers MUST dedupe on event_id before side effects"
         but src/webhooks/stripe.ts has no dedupe check on event_id
Verdict: NOT VERIFIED, RFC requires idempotency; current code does not implement it
```

If no authoritative doc exists, say so and fall back to code/runtime evidence. Never treat an undocumented assumption as verified.

## Output format

```markdown
**Claim:** <original claim>
**Hypothesis:** <falsifiable restatement>
**Evidence:** <command run and raw output>
**Verdict:** VERIFIED | NOT VERIFIED | INCONCLUSIVE
**Confidence:** High | Medium | Low
**Note:** <one line of context if needed>
```

## Worked example: the Verify move in a review

The plan claims something checkable; verify before asking, show the raw evidence, then let the verdict pick the next move.

**Plan excerpt:**
```
## Cleanup
Delete the `legacyExport` module. Nothing calls it anymore.
```

**Verify (no question yet):** "The plan claims nothing calls `legacyExport`. That's checkable, so verifying before asking."

```
Claim: "Nothing calls legacyExport anymore"
Evidence: grep -rn "legacyExport" src/ -> 2 call sites:
         src/reports/quarterly.ts:88
         src/admin/export.ts:14
Verdict: NOT VERIFIED: 2 active call sites outside the module
```

"NOT VERIFIED: `legacyExport` has two live call sites, `src/reports/quarterly.ts:88` and `src/admin/export.ts:14`. The deletion step needs a migration for those callers or the claim corrected. Which is it?"

**User:** "quarterly.ts is behind a feature flag we killed last month, so that path is dead. admin/export is real though. I'll add a step to move admin export onto the new exporter before the deletion."

**Accept and record:** "Recorded: migrate `src/admin/export.ts` to the new exporter before deleting `legacyExport`; the dead-flag path in quarterly.ts deletes with the module. Writing the migration step into Cleanup."

Tone throughout: reference the specific section and claim, no preamble praise, follow-ups sharper than first questions, acceptance brief and written into the file before moving on.

## Integration with plan review

During triage (Step 2), verify the plan's load-bearing checkable claims before the dialogue; a NOT VERIFIED claim drops its dimension a point and becomes the first question.

During dialogue (Step 3), when the user responds with a verifiable claim:

1. Recognize it is checkable ("this is under 100 lines", "we already handle that case", "the test covers this")
2. Pause the dialogue
3. Run the verification workflow
4. Report the verdict with the raw evidence
5. Use the verdict to choose the next move: ACCEPT, PUSH DEEPER, or REFRAME

Do not verify every claim, only those load-bearing for a plan decision or that seem surprising.

# Doc grounding

Ground the plan in documentation that already encodes decisions, then grill the rationale. Load during Step 1 when design docs, RFCs, ADRs, or library/API docs are relevant.

## Where to find docs

In order of authority, closest to the code first:

| Source | Where | What it tells you |
|---|---|---|
| ADRs / decision records | `docs/adr/`, `docs/decisions/`, `*.adr.md` | Why chosen, what was rejected, the tradeoff |
| Design docs / RFCs | `docs/`, `rfcs/`, linked in PRs or issues | Intended approach, constraints, open questions |
| READMEs | repo root, package roots | Conventions, setup assumptions, supported usage |
| Inline contracts | doc comments, `types`, schema files | Real interface vs the documented one |
| Library / API docs | the dependency's official docs | Supported APIs, deprecations, recommended patterns |
| Specs the user points to | wherever the user names | Source of truth for this work |

No docs in the repo? Say so and fall back to code-only grounding. Never invent doc content.

## Extract the core decisions

Pull **decisions** from each doc, not prose. Three parts:

- **Choice:** what was decided ("use optimistic locking", "single Postgres instance", "JWT in HttpOnly cookie")
- **Rationale:** why ("avoids lock contention at our write volume")
- **Validity window:** what breaks it ("only holds under ~100 writes/sec")

Capture compactly:

```
DECISION: <choice>
WHY: <rationale, quoted or paraphrased from the doc>
HOLDS WHILE: <the condition that keeps it valid>
SOURCE: <file:line or doc name>
```

Skip anything not load-bearing for this plan.

## Turn decisions into grilling questions

A decision becomes a question only when this work could invalidate it. Pressure-test the rationale and validity window, not the choice itself.

| Decision pattern | Grill it with |
|---|---|
| Approach chosen for a stated reason | "RFC picked X because [reason]. Does that still apply to what we're adding?" |
| Constraint / limit | "Doc assumes [limit]. Does this change push past it?" |
| Rejected alternative | "They rejected Y for [reason]. Anything changed that makes Y worth revisiting?" |
| Unstated assumption in the doc | "Design assumes [assumption] but never says so. Still true here?" |
| Doc contradicts the code | "Doc says X, code does Y. Which is source of truth here?" |

Use `interrogation-protocol.md`'s recommended-answer format: name the doc, quote the decision, propose your read.

## Anti-patterns

- Summarizing the docs back to the user. They wrote them; a recap burns a turn without advancing the plan.
- Re-asking what a doc plainly answers. Read it, fold the answer into your grounding, move on.
- Treating a doc as current truth when the code diverges. Verify against the code and flag the drift; planning against a stale doc bakes it in.
- Grilling every decision. Only ones this work could break earn a question; the rest waste the 5-10 question budget.

# Handoff plans

Read when a fresh session, a subagent, a teammate, or a cleared context will execute the plan. In Claude Code, approving a plan with the clear-context option or starting a new session to implement makes every plan a handoff plan; only a plan executed in the same conversation that wrote it is exempt.

## Why the executor is a stranger

The executor has not seen the interrogation. Every decision the user made in chat, every file the planner read, and every convention the planner noticed exists only in a context the executor does not have. The plan is the whole briefing. Anthropic's guidance for specs handed to a fresh session says the same: the useful ones "name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works."

## What to inline

- Code excerpts the executor must match, with `file:line` markers, trimmed to the decision-rich part (a type, a schema, a function signature, a state machine). Prose describing a contract drifts; the code does not.
- Conventions the codebase follows that a grep would not reveal: naming, where tests live, which helper to reuse, which module must not be imported from.
- The verification commands and their expected output, copied from the Verification section, so the executor can run them without reading anything else.

## STOP conditions

Assumptions that, if false, mean stop and report back rather than improvise. Each one is checkable in advance by the executor:

```markdown
## STOP conditions

Stop and report instead of continuing if any of these is false when you check it:

- `src/auth/session.ts` still exports `refreshToken(userId)` with a single argument
- The `users.email` column has a unique index (`\d users` in psql)
- `npm test -- --reporter=dot` passes on `main` before any change
```

A STOP condition names the assumption and how to check it. "If anything looks off" is not a STOP condition; the executor cannot check it.

## Finish line

A plan that says what trips a STOP but never what an acceptable finish looks like leaves an executor that trips nothing patching past the point the work stopped converging. State the finish as one of three outcomes:

- The capability works on the real path and the case that motivated the plan improved (name the command or observation that shows it).
- A genuine blocker was removed and the next one isolated (name it).
- The run stopped because finishing needs scope the plan does not cover (name the scope).

## Implementation-notes file

Name a notes file next to the plan (`<plan>.notes.md`) and instruct the executor to keep it. Two headings:

```markdown
## Deviations

- Plan said: <what the plan specified>
  Code required: <what the codebase forced>
  Taken: <the option chosen, and why it is the conservative one>

## How the run ended

<one of the three finish outcomes, with the evidence>
```

A deviation that is not a STOP condition never pauses the work: take the conservative option, log it, keep going. The notes file is what review reads afterwards; a handoff without one loses every decision made during execution, and the reviewer has only the diff to reconstruct them from.

## Reviewing the result

After implementation, the adversarial check is a fresh subagent reading only the diff, the plan, and the notes file: every requirement implemented, every listed edge case tested, nothing outside the plan's scope changed. Tell it to report gaps that affect correctness or the stated requirements, not style; a reviewer asked to find gaps will find some, and chasing every one over-engineers the result.

# Interrogation protocol

Use for an unresolved consequential decision or an explicitly requested interview. Use the host's available question interface; offer a recommendation grounded in evidence. There is no question quota.

## Contents

- Question decision tree
- Blindspot pass
- Recommended answer format
- Batching independent questions
- Fuzzy term patterns
- Respecting a request to proceed

## Question decision tree

Start at the root. Branch on what the codebase scan already told you.

```text
Intent clear?
├── NO → Ask: "What are you trying to achieve? My read is [X] because [evidence]."
└── YES
    Scope clear?
    ├── NO → Ask: "What's in, what's out? I'd keep it to [X] and skip [Y]."
    └── YES
        Reference to build on? (existing code, a library, a design, a site)
        ├── UNKNOWN → Explore the codebase first; then ask: "Is there code, a library, a design, or a site that already does this the way you want? Point me at it."
        ├── YES → Read it; its semantics are the spec. Ask: "Extend [module], or reimplement the same semantics alongside it?"
        └── NO
            Simplest approach obvious?
            ├── NO → Ask: "I see two approaches: [A] and [B]. I'd pick [A] because [reason]."
            └── YES
                Risky parts identified?
                ├── NO → Ask: "What's most likely to go wrong or take longest?"
                └── YES
                    Verification strategy?
                    ├── NO → Ask: "How will we know this works? I'd verify with [X]."
                    └── YES
                        Whole change as simple as it can be?
                        ├── NO → Ask: "Can this whole PR be radically simpler? I'd cut [X] / collapse [Y]."
                        └── YES → Synthesize. You have enough.
```

Don't walk the tree mechanically; skip branches the codebase scan already answered. It ranks what matters, it is not a script. When the user names a reference, read it and treat its semantics as the spec ("reimplement the same semantics as `vendor/rate-limiter`"), interrogating deviations only.

Challenge scope when there is a concrete cut to propose; do not ask a ritual closing question.

## Blindspot pass

When the user is unfamiliar with the area or asks for a "blindspot pass" / "unknown unknowns", their answers would be guesses. Before spending questions, surface two things and teach them back in 5-8 cited bullets, no lecture:

- **Unknown knowns:** repo decisions they would contradict (conventions, ADRs, prior art), found via `git log`, PRs, and docs.
- **Unknown unknowns:** what good looks like here, common potholes, and the questions they don't know to ask.

Then resume the tree; later answers win. This costs zero questions: exploration, not interrogation.

## Recommended answer format

Every question carries a concrete recommendation so the user reacts to something specific instead of generating from scratch.

**Good** (name the file, function, approach):

> **Q: Should we extend the existing `auth` middleware or build a new one?**
>
> My recommendation: extend `auth/middleware.ts`. It already validates tokens and has the hook points we need at line 45. A new one duplicates the refresh logic.

> **Q: How should we handle the case where the external API is down?**
>
> My recommendation: return cached data with a staleness indicator. The `cache/` module already stores responses with TTLs. Adding a `stale: true` flag is one line.

**Bad:**

> My recommendation: it depends on your needs. (Too vague. Pick a side.)

> My recommendation: we should probably think about whether to use approach A or B. (Still making the user decide.)

**Rule:** name the file, the function, the approach. If you can't be specific, you haven't explored enough: read more code before asking.

## Batching independent questions

One `AskUserQuestion` call can carry several questions. Batch only when no answer changes which question comes next: a greenfield spec with independent decisions (storage, auth provider, out-of-scope list), or a user who asked for a questionnaire. Keep one question per turn whenever answers branch, which is the normal case; a batch cannot follow up on the answer that reshapes the plan. Each batched question still carries its recommended option.

## Fuzzy term patterns

When you hear these, sharpen them:

| Fuzzy term | Ask this | Example sharpening |
|---|---|---|
| "handle auth" | What specifically? Validate token? Refresh? Redirect? | "Validate JWT in the API middleware" |
| "make it fast" | What latency target? For which operation? | "P95 under 200ms for list queries" |
| "clean up the API" | What's wrong now? Inconsistent naming? Missing validation? | "Rename endpoints to match resource nouns" |
| "add caching" | What are you caching? At what layer? What invalidation? | "Cache user profiles in Redis with 5-min TTL" |
| "improve the UX" | Which user flow? What's the friction? | "Reduce checkout form from 3 pages to 1" |
| "make it scalable" | What load? What bottleneck? | "Support 10k concurrent WebSocket connections" |
| "refactor this" | What's the pain? Readability? Coupling? Performance? | "Extract the payment logic into its own module" |
| "add error handling" | Which errors? What should the user see? | "Show a retry button on network timeout" |

Propose the sharp version and ask if it's right; never ask "what do you mean?" in the abstract.

## Respecting a request to proceed

"Just write the plan" and "skip questions" are instructions. Draft from the available evidence and state material assumptions. Leave a consequential unresolved decision at the step it blocks; continue the rest. Do not argue for an interview the user declined.

# Plan Quality Rubric

Used in Step 2 (Triage) to score each dimension 1-5 and find the weakest areas for deep-dive questioning.

## Scoring Scale

| Score | Label | Meaning |
|-------|-------|---------|
| 5 | Strong | Addresses this dimension with specifics. No visible gaps. |
| 4 | Adequate | Covers it but lacks some specificity. Minor gaps only. |
| 3 | Partial | Mentions it but significant gaps exist. Key scenarios unaddressed. |
| 2 | Weak | Barely touches it. Multiple critical gaps. |
| 1 | Missing | Does not address it at all. |

## Dimension-Specific Indicators

### Completeness

- **5:** Every new flow has explicit error handling. Rollback or recovery documented. Edge cases listed. Cleanup steps present.
- **4:** Main flows covered. Error handling mentioned but not specific. Minor edge cases missing.
- **3:** Happy path described. Error handling hand-waved ("handle errors appropriately"). No rollback.
- **2:** Only the core action described. No failure paths or edge cases.
- **1:** Describes what to build but not how it handles any non-ideal scenario.

### Feasibility

A good plan delivers a tracer bullet first: a minimum viable slice across the full stack to prove the approach.

- **5:** Approach validated. Dependencies confirmed. Performance characteristics known. Hardest parts identified with solutions. Tracer bullet or vertical slice identified.
- **4:** Approach reasonable. Most dependencies verified. One or two unvalidated capability assumptions.
- **3:** Approach plausible but unproven. Some steps vague. External dependencies mentioned without confirming they support the use case.
- **2:** Multiple steps rely on unverified assumptions. Key technical questions unanswered. Builds horizontal layers instead of proving a slice.
- **1:** Approach is aspirational. No evidence it works at the required scale/complexity.

### Scope

- **5:** Every item serves the stated goal. No "nice to have" mixed with requirements. States what is out of scope. Abstractions earned by repetition, not speculation. New code and dependencies justified against the ladder of least code.
- **4:** Mostly focused. One or two items could be deferred without affecting the goal.
- **3:** Several non-essential items. Premature abstractions or optimizations. Designing for hypothetical futures.
- **2:** Significant feature creep. Multiple items justified by "might need later." Wrong abstractions before the pattern is clear.
- **1:** Scope far exceeds the goal. Unclear what's core vs optional. Over-engineered.

### Testability

- **5:** Verification section present. Specific test cases or commands listed. Clear "done" criteria. Integration test strategy for external dependencies.
- **4:** Verification mentioned. Some test cases but not comprehensive. "Done" criteria at high level.
- **3:** "Add tests" without specifics. Verification section is one line. No integration test strategy.
- **2:** Testing mentioned in passing. No concrete test cases. No verification commands.
- **1:** No mention of how to verify the implementation works.

### Risk

- **5:** Failure modes identified. Blast radius stated. Mitigations present. Rollout strategy (gradual, feature-flagged) appropriate to risk level.
- **4:** Major risks identified. Blast radius roughly scoped. One or two mitigations.
- **3:** Risk acknowledged in general terms. No specific failure modes traced. No mitigation.
- **2:** Risk minimized ("this is low risk") without evidence. No failure mode analysis.
- **1:** No risk discussion. Assumes everything works first time.

### Assumptions

- **5:** Assumptions explicitly listed and marked verified or unverified. External conditions stated. Invalidation criteria present.
- **4:** Key assumptions stated. Most appear verified. One or two implicit assumptions identifiable.
- **3:** Some assumptions stated but several implicit ones unacknowledged. No invalidation criteria.
- **2:** Built on multiple unstated assumptions. Claims presented as facts without sources.
- **1:** No assumptions acknowledged. Reads as if the approach is self-evidently correct.

## Triage Decision

Use scores to locate gaps when scoring is requested. Fix gaps tied to acceptance criteria or operational consequences. Record unverified claims and unresolved choices; a score is a judgement, not proof. Stop when further changes would add speculative scope or when a user decision is required.

# Questioning Framework

Six dimensions for plan review, each with question templates and pushback patterns. Adapt templates to the plan; never ask verbatim generic questions. When a "look for" item is checkable against local code or docs (unused helper, unconfirmed library capability, doc that contradicts the plan), verify it yourself first (`claim-verification.md`) and lead with the evidence instead of a question.

## Contents

1. [Completeness](#1-completeness): missing flows, error paths, rollback
2. [Feasibility](#2-feasibility): unproven steps, external dependencies
3. [Scope](#3-scope): unnecessary scope, premature abstractions, wrong abstractions
4. [Testability](#4-testability): verification, "done" criteria, boundary tests
5. [Risk](#5-risk): blast radius, failure modes, broken windows
6. [Assumptions](#6-assumptions): unstated conditions, invalidation

## 1. Completeness

What must exist for this plan to work that is not mentioned?

**Question templates:**
- "You describe [X flow] but not what happens when [Y condition] occurs. What's the behavior?"
- "No rollback section. If this ships and breaks immediately, what's the recovery procedure?"
- "For the [API call / data flow / user action] in section [N], what happens on failure?"
- "What edge cases does [feature] need to handle that aren't listed?"
- "Where are the boundaries of this system? What gets validated at the edges?"

**Push pattern:** "You said 'handle errors appropriately'. Name the three likeliest errors and what the user sees for each."

**Look for:**
- New API calls or data flows without error handling
- State transitions without failure paths
- Missing cleanup or teardown steps
- No handling when external services are unavailable
- No boundary validation (user input, external APIs)

## 2. Feasibility

Which step requires something unproven, unfamiliar, or outside your control?

**Question templates:**
- "Which step requires something you haven't built before?"
- "What's the hardest technical problem here, and how confident are you in the approach?"
- "Does any step depend on an external system you don't control? What's its reliability?"
- "You're proposing [approach]. Verified it works at the scale you need?"
- "Section [N] assumes [library/service] can do [X]. Confirmed, or assumed?"
- "What's the tracer bullet here, the thinnest slice that proves the approach end-to-end?"

**Push pattern:** "You said this is 'straightforward'. Describe the implementation in 3 sentences. If you can't, it's not straightforward."

**Look for:**
- One-sentence steps that actually require significant implementation
- Libraries or APIs cited without evidence they support the use case (checkable: read the docs or types first)
- Performance assumptions without benchmarks
- "Then we just..." phrasing (minimizing complexity)
- No tracer bullet: plan builds horizontal layers instead of a vertical slice first

## 3. Scope

What's not strictly necessary to achieve the stated goal? Keep repetition when the proposed abstraction lacks a shared invariant, owner, lifecycle, or failure mode.

**Question templates:**
- "Which parts aren't required to achieve the goal stated in the Context section?"
- "If you had to ship in half the time, what would you cut?"
- "Is there a simpler approach that gets 80% of the value for 20% of the effort?"
- "[Feature X] is in the plan. What user problem does it solve that the rest doesn't?"
- "You're building [abstraction]. What invariant, owner, lifecycle, or failure mode does it protect today?"
- "These call sites look similar. Do they encode the same business rule, or only the same shape?"
- "What's the simplest thing that could work here? Why isn't the plan doing that?"

**Push pattern:** "What user problem does X solve? If you can't name a specific scenario, it's scope creep."

**Look for:**
- Abstractions justified by "we might need this later"
- Multiple approaches listed "for flexibility" when one would suffice
- Caching, optimization, or generalization before the basic path works
- Helpers, utilities, or wrappers called only once

## 4. Testability

How will you verify that each step worked correctly?

**Question templates:**
- "How will you verify [specific step] worked? What does success look like concretely?"
- "What does 'done' look like in observable terms for [feature]?"
- "Which parts are hardest to test, and what's your strategy for them?"
- "No test approach for [section]. How will you catch regressions?"
- "If this breaks silently, how long before someone notices?"
- "What are the boundary conditions for [input/state]? Are you testing those edges?"
- "Can you build in one step and run the tests in one step?"

**Push pattern:** "You said 'we'll add tests'. Name three specific test cases now. If you can't, the plan doesn't understand its own behavior."

**Look for:**
- No verification section or test strategy
- Integration points with no contract validation
- Manual-only verification for automatable checks
- No way to verify the migration/deployment succeeded
- No boundary/edge case testing mentioned
- No pre/post-condition assertions at critical state transitions

## 5. Risk

What is the worst realistic outcome if this plan is implemented as written? Don't remove a fence until you know why it was put up.

**Question templates:**
- "What's the single worst thing that could happen if this ships as planned?"
- "If step [N] fails, what's the blast radius? What else breaks?"
- "What's the risk to existing functionality that works today?"
- "Who else is affected if this goes wrong? Just you, or other teams/users?"
- "How confident are you that [dependency] won't change under you?"
- "You're removing/changing [existing code]. Know why it was there?"
- "Is this leaving the campground cleaner than you found it, or creating technical debt?"

**Push pattern:** "You said risk is 'low'. What evidence supports that? Have you traced the failure modes?"

**Look for:**
- Shared state modifications without concurrency consideration
- Database migrations on large tables without downtime strategy
- Changes to authentication or authorization paths
- Removing or modifying code used by other teams (checkable: grep for call sites before asking)
- Deploying without a feature flag or gradual rollout
- Removing existing code without understanding why it exists (Chesterton's fence; `git log` the file before accepting "it's unused")

## 6. Assumptions

What does this plan take for granted that could be wrong?

**Question templates:**
- "What does this plan assume about [users / infrastructure / data / performance] that you haven't verified?"
- "What external conditions must be true for this to work?"
- "What would invalidate this entire approach?"
- "You're assuming [X based on plan text]. Source: measurement, documentation, or intuition?"
- "If [stated assumption] is false, which parts of the plan survive?"

**Push pattern:** "What happens if that assumption is false? Is there a Plan B, or does the whole thing collapse?"

**Look for:**
- Performance claims without measurements
- "Users will..." statements without evidence
- Compatibility assumptions (API versions, browser support, OS features)
- Timing assumptions (this will be fast enough, this will complete before that)
- Implicit dependencies on team knowledge or undocumented behavior

# Splitting work into slices

The exit from Create mode when the work is too big for one plan, and from Review mode when Scope cannot reach 5/5 because the plan is really two plans. The output is a set of **vertical slices**, one ticket each, every ticket declaring what blocks it.

## Contents

- When to split
- Draft the slices
- Wide refactors: expand and contract
- Confirm granularity before publishing
- Publish the slices
- Ticket shape
- What a fan-out runner reads
- Anti-patterns

## When to split

Split when any of these hold:

- The interrogation passed 10 questions without converging. More detail buys nothing: the plan cannot be executed in one pass.
- The plan has more than one shippable outcome. Two things a user could notice separately are two plans.
- Nothing can be verified until the last step lands. A plan whose Verification section only runs at the end is a stack of layers, not a plan.
- Review keeps Scope below 5/5 because items serve different goals and cutting either one drops a current requirement.

Do not split to escape the interrogation. Slicing needs the same understanding a single plan needs: intent, scope, and the frame settled first. Split before the frame is settled and you slice the wrong axis, then every slice inherits the mistake.

Splitting is also wrong when the pieces are only sequential steps of one small change. Two tickets that a single agent would do in one sitting cost two worktrees, two reviews, and two merges to buy nothing.

## Draft the slices

Each slice is a **tracer bullet**: a narrow but complete path through every layer the change touches (schema, API, UI, tests), never a horizontal slice of one layer.

- A finished slice is demoable or verifiable on its own, on the main branch, with no other slice merged.
- Each slice fits one fresh context window: an agent that has never seen this conversation can read the code it touches, make the change, and run the verification without running out of room. If you cannot name the single command or observation that proves the slice, it is too big or too horizontal.
- Prefactoring comes first, as its own slice. Make the change easy, then make the easy change.
- Slice titles name the behaviour that works when the ticket closes, not the layer it edits.

Then give each slice its **blocking edges**: the slices that must finish before it can start. A slice with no blockers starts immediately.

A blocker is a slice whose absence makes this one impossible to build or impossible to verify. A slice that merely touches the same files is not a blocker. Get this wrong in the loose direction and it is expensive: a fan-out runner skips any ticket whose blockers are still open, so one decorative edge parks work that could have started, silently, until a human notices the ticket never picked up. Aim for a shallow graph: most slices unblocked, one chain where the dependency is real.

## Wide refactors: expand and contract

A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. This is the one exception to vertical slicing. Do not force it into a tracer bullet; sequence it instead:

1. **Expand:** add the new form beside the old one so nothing breaks. One ticket, no blockers.
2. **Migrate:** move the call sites over in batches sized by blast radius (per package, per directory). Each batch is its own ticket blocked by the expand, and each stays green because the old form still exists.
3. **Contract:** delete the old form once no caller remains. One ticket, blocked by every migrate batch.

When even the batches cannot stay green alone, keep the sequence but let them share an integration branch, and add a final integrate-and-verify ticket blocked by all of them. Green is promised only there, and the tickets must say so.

## Confirm granularity before publishing

Present the proposed breakdown as a numbered list. For each slice show:

- **Title:** short, names the outcome
- **Blocked by:** the slices that gate it, or "none"
- **What it delivers:** the end-to-end behaviour that works once it closes

Then ask three questions:

- Does the granularity feel right, too coarse or too fine?
- Are the blocking edges real, or is anything listed that merely touches the same area?
- Should any slices merge or split further?

Iterate until the human approves. Publish nothing before then: tickets are visible to other people and to any fan-out runner watching the tracker, so an unapproved breakdown is not a draft, it is work already dispatched.

## Publish the slices

You write the tickets yourself, exactly as you open a PR. Nothing downstream writes to a tracker; a fan-out runner only reads what you published.

Publish in dependency order, blockers first, so each ticket's edges can reference identifiers that already exist.

- **A real tracker (Linear, GitHub, ...):** one issue per slice. Set the tracker's **native** blocking relation ("Blocked by" on Linear), not just a line of prose. A runner reads the relation; a blocker that exists only in the description is invisible to it and the ticket will pick up early.
- **Local markdown files:** one file per slice at `<plan-dir>/slices/<NN>-<slug>.md`, numbered from `01` in dependency order, one ticket per file and never one combined file. There is no tracker to read the edges, so the `Blocked by` line is for the human driving pickup.

Do not modify or close the parent issue.

Finally, record the breakdown in the plan file under a `## Slices` heading: each slice's identifier or file path, its title, and its blockers. When the split happened during interrogation and no plan file exists yet, write the lightweight one now (title, context, approach) and put `## Slices` in it. Without that index the plan and the tickets drift apart the moment either changes, and Review has nothing to act on.

## Ticket shape

```markdown
# <NN> <Title>

**What to build:** the end-to-end behaviour this ticket makes work, from the
user's perspective. Not a layer-by-layer implementation list.

**Blocked by:** <the tickets that gate this one, or "none, can start immediately">

## Acceptance criteria

- [ ] Criterion 1
- [ ] Criterion 2
```

Every criterion must be checkable by someone holding only the diff and the repo. "Works correctly" is not a criterion; "the list still renders when the API returns 500" is.

Avoid file paths and code snippets: they go stale between publishing and pickup. The exception is a snippet that encodes a decision more precisely than prose can (a schema, a state machine, a type shape), trimmed to the decision-rich part.

## What a fan-out runner reads

A runner that picks these tickets up maps each one into a fixed contract, so write to it:

| Field | Comes from | Consequence |
|---|---|---|
| identifier | the tracker | how the human approves, rejects, and merges the run |
| title | the ticket title | names the worktree and the PR |
| description | the ticket body | passed verbatim as the contract the agent implements |
| criteria | the tracker's native sub-items (Linear sub-issues, checklist items) | one graded acceptance criterion each |
| blockedBy | the native blocking relation | open blockers mean the ticket is skipped, not queued |

Two consequences worth planning around. Sub-items are read as **acceptance criteria of their parent**, so do not make the slices sub-items of the epic and then dispatch the epic: dispatch the slices. And do not spend criteria on the repo's standing bar (tests pass, lint passes, a PR is open); that bar is constant and the runner already applies it. Criteria are for what makes *this* slice correct.

## Anti-patterns

- **Horizontal slices** titled "schema", "API", "UI". Nothing is demoable until the last one lands, and the first two cannot be verified at all.
- **"Phase 1 / Phase 2 / Phase 3"** titles. They encode order, which the blocking edges already carry, and hide the outcome.
- **Blockers used to mean "related"**. Every false edge parks a ticket a runner would otherwise have started.
- **Publishing before approval.** Retracting means deleting tickets other people have already seen.
- **A slice that only lands green on another slice's unmerged branch.** That is a wide refactor wearing a tracer bullet costume; sequence it as expand and contract instead.
- **Splitting instead of interrogating.** A breakdown built on an unsettled frame slices the wrong axis and multiplies the error by the number of tickets.