feat(skills/developing-a-feature): distill the spec into the repo's decision-record format at teardown (#28)

Author: sourcehawk

skills/developing-a-feature/SKILL.md

@@ -128,7 +128,12 @@ Run the loop on the **final** PR diff. The Step 7 teardown is the last commit on
 
 ### 7. Tear down the planning artifacts
 
-Delete the plan + state file once the work is genuinely done. The spec stays — it's the durable ADR. The plan and state file are scratch; leaving them committed past readiness pollutes the repo with stale operational state that future `grep`s have to wade through.
+Delete the plan + state file once the work is genuinely done. They are scratch; leaving them committed past readiness pollutes the repo with stale operational state that future `grep`s have to wade through.
+
+**The spec's fate depends on where the repo keeps its durable decision records.** Check for an established convention: a `docs/adrs/` (or equivalent) directory, an ADR-authoring skill, an architecture log.
+
+- **The repo has one** → the spec does not merge as-is. Distill its lasting architectural decisions into that format — one record per coherent decision bundle, following the house format and any authoring skill the repo provides — present the drafts for user review, and land the approved records with the teardown; the spec is deleted alongside the plan and state file. A year out, engineers read the repo's canonical decision record, not a feature-scoped design doc in a scratch path; a spec that "stays" outside that record is durable in letter, not in function. The distilled records carry the decisions, alternatives, and consequences; the operational detail they leave behind lives on in the merged code, its tests, and the docs written at Step 5.
+- **The repo has none** → the spec stays as the feature's durable design record.
 
 **The teardown is the last commit on the feature branch; what gates it depends on whether the repo runs CI on the integration PR.** Settle that first by inspecting the repo's CI configuration — is a pipeline wired to run on this PR's branch? Decide from the configuration, not from a momentary `gh pr checks` reading: zero checks *reported* can mean either "no CI exists" or "CI hasn't registered yet," and you can't tell those apart by polling.
 
@@ -161,6 +166,7 @@ The teardown does not change where the flow ends. In the models that end in a fi
 | "I'll open the integration PR before the last sub-PR is self-merged" | The integration PR's diff is supposed to be the whole feature. An in-flight sub-PR means the integration PR will be re-pushed mid-review. Wait. |
 | "I'll create `feature/<slug>` off `origin/main` in step 3"           | Planning already created it and committed the spec/plan/state onto it. `-b feature/<slug>` errors ("already exists") and re-creating off `origin/main` orphans the planning artifacts. Reuse the existing branch; attach a worktree to it. |
 | "Tests pass locally and the PR is ready, so I'll tear down plan/state now" | When CI runs on the PR, local green and "ready" aren't the gate — if it comes back red you fix forward, with no state file if you deleted it. Tear down on the PR's checks going green. (Repo has no CI configured for this branch? Then the local suite *is* the gate — proceed.) |
+| "The spec stays — it's the durable record"                           | Only in repos with no decision-record convention of their own. Where `docs/adrs/` (or equivalent) exists, distill the lasting decisions into it — with user review — and delete the spec with the other scratch artifacts. The canonical record is what future engineers actually read. |
 | "`gh pr checks` reports no checks, so I'll keep polling until CI shows up" | Zero checks reported isn't the same as CI pending. Inspect the repo's CI configuration: if no pipeline runs on this branch, none will ever appear and polling just stalls the workflow. Proceed on the local suite you already pasted. |
 | "It's one PR, I'll just implement all the tasks myself in this session" | If the plan has 2+ independent tasks, that skips per-task review — the author and reviewer are the same context, so the bug that slipped into task 1 survives into the PR. Count the independent tasks; at 2+ drive it through `superpowers:subagent-driven-development`. |
 | "The tasks are independent, so I'll knock them out back-to-back myself" | Independence is the signal *for* task-by-task dispatch with review between, not against it — it's exactly when SDD pays off. Direct implementation is for one cohesive change or a strictly sequential chain. |