Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .agents/skills/epic-lifecycle/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,9 @@ The epic-specific delta:
without it. Dispatch directly, and hold that row's merge gate until the change lands.
- **A dispatch here is a worktree, always.** N workers are live on their own branches; a
sub-agent you spawn without `isolation: worktree` shares this checkout with them.
- **A fact you write into a brief or a status line is read when you write it.** Read an issue's
or a PR's state from Linear or GitHub at that moment; get a rule's merge state or what the code
does from a fresh `scout` or worker lookup and cite its result — never from an earlier wake's record.

## The loop (each invocation)

Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/issue-implement/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Both disciplines are embedded into the implementer sub-agent prompt at dispatch

**Red is a gate, not a suggestion.** For any change with observable behaviour, the discipline is not satisfied by writing the test after the code, or writing the test and the fix together and only confirming green. The flow is always: write ONE behavioural test → run it → observe it fail for the intended reason (not a typo, import error, or missing fixture) → write the minimal code → observe it pass. Both the failing output and the passing output are evidence (BP-003) — "tests pass" alone proves nothing if the test was never seen to fail. This applies everywhere this skill drives a code change: Step 5A/5B implementation (tracer-bullet loop, red-before-green per slice) and Step 10.4 fixes made in response to PR review (every regression test shown failing against the un-fixed code first). Step 6's completeness review checks for this evidence, not just green tests.

**A check with no before-state owes a blast radius instead.** Some checks are green before the change and green after — a **negative** assertion (`not.toMatch`, "nothing was hired"), a **cardinality** claim ("exactly three"), a **control or goal-check leg** that grades a run, an **equivalence** between two artifacts — so the flow above is satisfiable in full while the check cannot fail at all. Break **the property the check claims**, not the implementation, and report what you broke, which checks went red, and **that nothing else did**. The third part carries the weight: where a fixture is too clean to contain the failure, perturbing the subject fails *nothing*, and only the blast radius makes that visible. A check you cannot write that report for is not evidence yet.
**A check with no before-state owes a blast radius instead.** Some checks are green before the change and green after — a **negative** assertion (`not.toMatch`, "nothing was hired"), a **cardinality** claim ("exactly three"), a **control or goal-check leg** that grades a run, an **equivalence** between two artifacts — so the flow above is satisfiable in full while the check cannot fail at all. Break **the property the check claims**, not the implementation, and report what you broke, which checks went red, and **that nothing else did**. The third part carries the weight: where a fixture is too clean to contain the failure, perturbing the subject fails *nothing*, and only the blast radius makes that visible. A check you cannot write that report for is not evidence yet. **The unit is the assertion, not the leg:** every outcome the leg claims maps to an assertion, and each assertion is shown able to fail — a control that reddens its leg proves neither, and an assertion that passes on an absence, on an empty loop, or on a state it never waited for stays green beside it.

**Exceptions.** (a) Pure characterization/parity work — swapping an implementation while holding pre-existing tests green (see `tdd` → "When NOT to use TDD") — has no red-green cycle by design; the discipline there is that the parity tests already existed *before* the change and continue to pass, not that anything was ever red. This exception covers holding **pre-existing** tests green; it does not reach a *new* assertion you add over existing behaviour, which owes the red state and blast radius above. (b) Trivial, mechanical edits with no behavioural surface — config values, docs, renames — don't need a test at all. Anything with observable behaviour (an item emitted, a return value, a state change, a symptom that's now fixed) gets the red gate; when in doubt, treat it as observable.

Expand Down Expand Up @@ -337,7 +337,7 @@ This is the critical quality gate. **Invoke `review`** on the change (the implem
- **Coherence** (`audit-coherence`) — does the solution cohere with `docs/philosophy.md` and the surrounding patterns? The apex lens: it catches the "directionally-right spec but the design feels off" failure the others structurally can't. A coherence break usually means reshaping the approach, not patching lines.
- **Restraint** (`second-look`) — overbuilt / YAGNI / 80-20 / what can be subtracted (BP-038)?
- **Correctness** — bugs and logic errors + the second-path checklist (BP-035). Changesets (BP-022) are opt-in, so the lens flags a fragment that is present and wrong, never a missing one.
- **Completeness** (a spec is in scope) — every spec requirement built and nothing extra, **red demonstrated** (the failing output captured before the fix — and, for a check with no before-state, the blast radius: what was broken, which checks went red, and that nothing else did), and the **goal proven** on a real model (or the documented "no goal check applies" justification; for bugs, diagnose's real-path confirmation).
- **Completeness** (a spec is in scope) — every spec requirement built and nothing extra, **red demonstrated** (the failing output captured before the fix — and, for a check with no before-state, the blast radius: what was broken, which checks went red, and that nothing else did — per assertion, with every claimed outcome asserted), and the **goal proven** on a real model (or the documented "no goal check applies" justification; for bugs, diagnose's real-path confirmation).

Depth follow-ups (`improve-codebase-architecture`) come back as non-blocking notes. If the area is unfamiliar or large, `review` may run the depth lens too.

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/issue-implement/implementer-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ Agent tool (general-purpose):
- What you implemented
- What you tested and results
- **Key decisions you made (with ramifications):** any choice the spec left open that you resolved, any deviation, any tradeoff under a constraint — the decision, the alternative you rejected, and what it locks in or rules out. The orchestrator compiles these across tasks into the PR's top-5. If the task was mechanical with no real decisions, say so.
- **Red/green evidence:** for every new behavioural test or regression test you wrote, the actual failing output you captured before the fix/implementation existed, and the passing output after. "Tests pass" alone does not satisfy this — a test never observed to fail proves nothing. If a check has no before-state — it grades a claim the change itself makes (an equivalence, a count, an identity, an absence, a verdict) rather than behaviour you are about to write — report its **blast radius** instead: break the property the check claims, then say what you broke, which checks went red, and **that nothing else did**. The last part carries the weight: a fixture too clean to contain the failure shows up as a perturbation that fails nothing. If this task is one of the documented exceptions (pure characterization/parity refactor holding pre-existing tests green, or a trivial mechanical edit with no behavioural surface), say so instead of fabricating evidence.
- **Red/green evidence:** for every new behavioural test or regression test you wrote, the actual failing output you captured before the fix/implementation existed, and the passing output after. "Tests pass" alone does not satisfy this — a test never observed to fail proves nothing. If a check has no before-state — it grades a claim the change itself makes (an equivalence, a count, an identity, an absence, a verdict) rather than behaviour you are about to write — report its **blast radius** instead: break the property the check claims, then say what you broke, which checks went red, and **that nothing else did**. The last part carries the weight: a fixture too clean to contain the failure shows up as a perturbation that fails nothing. Do it per assertion, not per leg: every outcome the leg claims has an assertion, and each is shown able to fail. If this task is one of the documented exceptions (pure characterization/parity refactor holding pre-existing tests green, or a trivial mechanical edit with no behavioural surface), say so instead of fabricating evidence.
- **Goal verdict:** for a TDD task, if the spec named a slice-level goal check runnable after this task, the real-model command/path and its PASS/FAIL verdict; if the goal proof is end-to-end, say it's deferred to the orchestrator (don't run it early or invent a PASS). For a Bug task, the real-path confirmation (`fsdev run`) that the user-visible symptom is gone, or "N/A — type/unit-only regression." Mocked specs don't prove the goal.
- Files changed
- Self-review findings (if any)
Expand Down
3 changes: 2 additions & 1 deletion .agents/skills/issue-implement/spec-reviewer-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ Agent tool (general-purpose):
equivalence, a count, an identity, an absence, a verdict) — owes a
**blast radius** in place of the failing output: what the implementer
broke, which checks went red, and that nothing else did. A report
missing the third part is not evidence; FAIL it. Exceptions: pure
missing the third part is not evidence; FAIL it. So is one given per
leg rather than per assertion, or a claimed outcome with no assertion. Exceptions: pure
characterization/parity work holding pre-existing tests green across
a swap, and trivial mechanical edits with no behavioural surface —
neither needs red evidence.
Expand Down
Loading
Loading