DevFoundry/.devfoundry/skills/technical-spec.md

Skill: Technical Spec Generation

Purpose: Convert confirmed requirements into a formal technical specification.

Steps

1. Read specs/.spec-counter for the next available integer ID. Zero-pad it to 3 digits (e.g. 1 -> 001) to form <id>. Copy specs/templates/spec-template.md into specs/active/SPEC-<id>-<short-name>.md, then increment the value in specs/.spec-counter by 1 and save it, so the next spec gets a unique ID. Never reuse an ID, even if a spec is later abandoned.
2. Fill in Business Context, Acceptance Criteria, and Technical Design sections.
3. Define data model/schema changes explicitly, including dialect-specific syntax. 3a. Before finalizing Target Files, check every other spec currently in specs/active/ for overlap with this list. If another active spec already lists one of the same files, flag it to the user and note the conflicting spec ID in this spec's Business Context — do not silently proceed with both specs touching the same file concurrently.
4. Define function/API contracts with explicit parameter types.
5. Break the work into an atomic implementation checklist per .devfoundry/skills/task-decomposition.md, pairing each implementation task with a preceding failing-test (or manual-verification, for legacy stacks) task per the TDD rule in .devfoundry/rules/general.md.
6. Mark spec status as DRAFT and present to the user for approval before implementation begins.

Amending an APPROVED or IN PROGRESS Spec

An APPROVED (or later) spec's Acceptance Criteria and Technical Design are frozen. If the user requests a genuine scope change (not a bug in the Builder's execution) after that point:

1. Do not edit the frozen sections in place. Append a new ## Revision <n> — <YYYY-MM-DD> section to the bottom of the spec file describing what changed and why.
2. Update the affected Acceptance Criteria / Technical Design / Implementation Plan entries, keeping the original text visible above the revision (strike through or annotate as superseded — do not delete it).
3. Set the spec's Status field to REVISED.
4. Present the revision diff to the user for approval, the same as the original DRAFT.
5. Once approved, set Status back to IN PROGRESS (or APPROVED if implementation has not started yet) and continue.
6. If the change is large enough that it is effectively a new feature, decompose it into a new spec (new ID from specs/.spec-counter) instead of revising this one, and note the cross-reference in both files.