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

[sourcehawk]

Problem

Step 7's teardown doctrine said "The spec stays — it's the durable ADR" unconditionally. In repos that maintain their own decision-record convention (an established docs/adrs/ with a house format), that leaves the feature's lasting decisions buried in a feature-scoped design doc at a scratch path outside the record engineers actually read — durable in letter, not in function. In a live session the user explicitly ordered the spec artifacts removed from the final PR and replaced with two house-format ADRs; a baseline agent following the skill's literal text kept the spec and only bridged the gap by consciously overriding the skill with its own judgment.

Change

skills/developing-a-feature/SKILL.md Step 7: the spec's fate becomes conditional on an observable predicate. Repo has a decision-record convention → distill the spec's lasting decisions into that format (house format, repo's authoring skill if one exists, user review of the drafts), land the records with the teardown, and delete the spec alongside the plan and state file. Repo has none → the spec stays, as before. One matching red-flag row.

Verification (writing-skills RED → GREEN)

• RED: baseline agent kept the spec per the literal text and had to improvise the ADR extraction as a self-admitted deviation ("satisfied in letter but not in function").
• GREEN: with the edit, the same scenario yields the full sequence from the skill itself: distill via the repo's ADR skill, user-review gate, ADRs land in the teardown commit that deletes the spec, decisions findable in docs/adrs/ a year out.

[Copilot]

Pull request overview

Updates the developing-a-feature skill’s Step 7 teardown guidance so “the spec stays” is no longer unconditional, ensuring long-lived architectural decisions end up in the repo’s actual decision-record system when one exists.

Changes:

• Makes spec retention conditional: if the repo has an established decision-record convention (e.g., docs/adrs/ or equivalent), distill decisions into that format and delete the spec during teardown; otherwise keep the spec as the durable record.
• Adds explicit instructions to follow house ADR format / any ADR-authoring skill and to gate distilled records on user review.
• Adds a matching red-flag entry clarifying that “the spec stays” applies only when no decision-record convention exists.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.