Compare commits

..

4 Commits

2 changed files with 23 additions and 78 deletions

View File

@@ -134,14 +134,9 @@ a ledger file, not only in todos.
- Create the ledger with its identity as the first line:
`# SDD ledger — plan: <plan file path>`.
- During that same Setup read, copy the plan's Global Constraints section
verbatim into `<workspace>/constraints.md`. Every dispatch's binding
constraint values paste from that file — the plan itself stays closed
verbatim into `<workspace>/constraints.md`. The global-constraints block
you hand reviewers pastes from that file — the plan itself stays closed
after Setup, even across compaction.
- The workspace is never committed to the project repo. Do not `git add`
anything under it, and never write a commit whose purpose is to record,
correct, or tidy a workspace artifact — reports and ledgers are session
records, not deliverables. If the repo lacks a `.gitignore` entry for
`.superpowers/`, leave the directory untracked rather than committing it.
- The ledger is your recovery map: the commits it names exist in git even
when your context no longer remembers creating them. After compaction,
trust the ledger and `git log` over your own recollection.
@@ -227,15 +222,9 @@ and fix-round diffs need it.
first — it is your requirements, with the exact values to use verbatim";
(3) interfaces and decisions from earlier tasks that the brief cannot
know; (4) your resolution of any ambiguity you noticed in the brief;
(5) the report-file path and report contract; (6) the plan's binding
constraint values — any Global Constraint that mandates an exact
mechanical form (commit-message rules, naming rules, fixed literals) —
pasted verbatim. Task-specific exact values (numbers, magic strings,
signatures, test cases) appear only in the brief; binding constraint
values are the one exception — they ride in EVERY dispatch, because a
subagent that must recall a constraint from memory will reconstruct it
from its own priors instead. Never make a subagent read the whole plan
file.
(5) the report-file path and report contract. Exact values (numbers,
magic strings, signatures, test cases) appear only in the brief. Never
make a subagent read the whole plan file.
- **Report file:** name the implementer's report file after the brief
(brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
the dispatch prompt. The implementer writes the full report there and
@@ -295,10 +284,6 @@ needed.
- **Reviewer inputs:** the task reviewer gets three paths — the same brief
file, the report file, and the review package — plus the global
constraints that bind the task.
- **Persist the verdict:** when the review returns, write its full text to
`<workspace>/task-<N>-review.md` before acting on it. The file is the
gate: completion checks for the artifact, not for your memory of a
verdict.
- The global-constraints block you hand the reviewer is its attention
lens. Copy the binding requirements verbatim from the plan's Global
Constraints section or the spec: exact values, exact formats, and the
@@ -349,26 +334,22 @@ scoped re-review. Five rounds maximum per task:
verbatim. Its context is intact: it knows the task, the code, and its own
choices. If your harness cannot send another message to a live subagent,
dispatch a fresh implementer carrying the brief path, the report-file path,
the findings, and the binding constraint values verbatim — the report file
is the persistent memory either way.
and the findings — the report file is the persistent memory either way.
**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
Model Selection), with the brief path, the report-file path, the open
findings, the binding constraint values verbatim, and this framing: "A
prior implementer attempted this task [N] times; you own it now. Read the
report file for what was tried." A loop that survives three resumes usually
means the implementer cannot see its own problem — fresh eyes and a
capability bump in one move.
findings, and this framing: "A prior implementer attempted this task
[N] times; you own it now. Read the report file for what was tried." A loop
that survives three resumes usually means the implementer cannot see its
own problem — fresh eyes and a capability bump in one move.
**Every round, either way:** the implementer fixes, re-runs the tests
covering the amended code, appends its fix report to the same report file,
and returns the short contract. Before re-dispatching the reviewer, confirm
the fix report contains the covering tests, the command run, and the output;
dispatch the re-review once all three are present. Name the covering test
files in the fix message — a one-line fix does not need the whole suite.
Append the re-review's returned text to `<workspace>/task-<N>-review.md` as
well — the artifact accumulates every verdict, and the file's last entry is
the one completion relies on.
the fix report contains the covering tests, the command run, and the
output; dispatch the re-review once all three are present. Name the
covering test files in the fix message — a one-line fix does not need the
whole suite.
**The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD`
where FIX_BASE is the head the previous review saw, and dispatch
@@ -413,20 +394,10 @@ message as your other bookkeeping:
- `Task <N>: complete (commits <base7>..<head7>, review clean)`
- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
tripped breaker
- `Task <N>: complete (commits <base7>..<head7>, deviation parked: <rule>)`
when a landed commit violates a mechanical constraint that nothing
downstream builds on. Record the ruling in the ledger. A green build with
a parked, recorded deviation is complete — do not fail the task, and do
not rewrite landed history to chase cosmetics. A load-bearing violation
is different: that is a BLOCKED, not a deviation. This valve is not the
breaker: it needs no exhausted fix rounds — a mechanical deviation
discovered at completion parks here directly, with its ruling in the ledger.
Then mark the todo complete and move on — but only once
`<workspace>/task-<N>-review.md` exists; a completion line without its review
artifact is invalid, whatever you remember about the review. Never move to
the next task while the review has open Critical/Important issues that are
neither fixed nor parked-with-ruling at the cap.
Then mark the todo complete and move on. Never move to the next task while
the review has open Critical/Important issues that are neither fixed nor
parked-with-ruling at the cap.
## Final Review
@@ -442,22 +413,17 @@ the ledger's deferred-minor and parked lines so it can triage which must be
fixed before merge. Build that dispatch from the ledger alone — the
completion lines, parked rulings, and deferred minors are the whole-run
summary; do not re-read the plan, the spec, or per-task reports to
reconstruct what the ledger already states. Write the returned review to
`<workspace>/final-review.md` before dispatching any fix wave — the merge
decision cites the artifact, not a recollection.
reconstruct what the ledger already states.
If the final whole-branch review returns findings, dispatch ONE fix subagent
with the complete findings list and the binding constraint values
verbatim — not one fixer per finding.
with the complete findings list — not one fixer per finding.
Per-finding fixers each rebuild context and re-run suites; a real
session's final-review fix wave cost more than all its tasks combined.
Then run exactly one scoped re-review of the fix wave
(`scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
[re-review-prompt.md](re-review-prompt.md)).
Adjudicate any residual findings as in the task loop's breaker: park with
rulings, or stop on load-bearing ones. The same valve applies to
mechanical-constraint misses discovered at the end: non-load-bearing means
parked with a ruling, not a failed branch. There is no second fix wave —
rulings, or stop on load-bearing ones. There is no second fix wave —
residual load-bearing findings surface to your human partner when
finishing-a-development-branch presents the options.

View File

@@ -15,12 +15,6 @@ Subagent (general-purpose):
Read your task brief first: [BRIEF_FILE]
It contains the full task text from the plan.
## Binding Constraint Values
[CONSTRAINT_VALUES — the plan's mechanical constraints, pasted verbatim
by the dispatcher. If a rule here mandates an exact form (commit-message
text, naming, fixed literals), reproduce it exactly — never from memory.]
## Context
[Scene-setting: where this fits, dependencies, architectural context]
@@ -42,12 +36,8 @@ Subagent (general-purpose):
2. Write tests (following TDD if task says to)
3. Verify implementation works
4. Commit your work
5. Immediately after each commit, verify it against the Binding Constraint
Values above (commit-message rules, naming rules, fixed literals) while
history is still local. A miss is cheap now — amend or forward-fix at
once — and expensive after your work is delivered.
6. Self-review (see below)
7. Report back
5. Self-review (see below)
6. Report back
Work from: [directory]
@@ -106,10 +96,6 @@ Subagent (general-purpose):
- Did I only build what was requested?
- Did I follow existing patterns in the codebase?
**Constraints:**
- Does every commit message satisfy the Binding Constraint Values exactly?
- Did I reproduce mandated literals from the constraint text, not from memory?
**Testing:**
- Do tests actually verify behavior (not just mock behavior)?
- Did I follow TDD if required?
@@ -118,12 +104,6 @@ Subagent (general-purpose):
If you find issues during self-review, fix them now before reporting.
If a constraint violation is already in a landed commit you cannot safely
amend, forward-fix it in a new commit when possible; when it is not, report
the deviation explicitly with Status DONE_WITH_CONCERNS — never report the
task incomplete solely for a cosmetic miss on an otherwise green build.
Whether the deviation parks or blocks is the dispatching controller's call.
## After Review Findings
If the task review finds issues, you will be resumed with the findings.
@@ -156,8 +136,7 @@ Subagent (general-purpose):
If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
itself — the controller acts on it directly.
Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness, or
when you are reporting a known deviation you could not safely fix.
Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
information that wasn't provided. Never silently produce work you're unsure about.
```