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. Run the Spec Readiness Checklist below.
7. Mark spec status as DRAFT and present to the user for approval before implementation begins.

Spec Readiness Checklist

• Status is DRAFT.
• Business Context, Acceptance Criteria, Technical Design & Contracts, Implementation Plan, Verification & Regression Plan, and Target Files are complete.
• Active specs in specs/active/ have been checked for Target Files overlap.
• Build/test/lint commands are documented in .devfoundry/references/environments.md, or the spec explicitly records that no command exists for the affected stack.
• If database changes are included, current schema notes, target-engine DDL, dependent queries/views/reports, and rollback or backup steps are documented.
• If no database/schema changes are included, the Data Model / Schema Changes section records exactly: No schema changes; rollback is git revert.
• Every implementation task has a preceding test/manual-verification task and includes space for completed: <YYYY-MM-DD HH:MM> timestamps.

Abandoning a DRAFT Spec

If the user cancels a DRAFT spec before approval:

1. Set the spec's Status field to ABANDONED.
2. Add a brief cancellation reason in Business Context or a final note at the bottom of the spec.
3. Move it to specs/archive/SPEC-<id>-<short-name>.md.
4. Do not decrement specs/.spec-counter and do not reuse the ID.

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.