Add Functional Spec
Always use the skill
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
Workflow
- Identify the target file. If ambiguous, ask the user.
- Read the entire file to understand existing definitions, implementation reqs, and all current functional specs (including those in modules).
- Draft the functional spec following the rules below.
- Analyze complexity — use the
analyze-if-func-spec-too-complex
- Check for conflicts with every existing functional spec — this is critical. Run once with the new spec plus all existing specs (in the file and in any chain) as a single batch. The batched analyzer returns every conflicting pair in one call — do not invoke a pair-by-pair analyzer. For each conflicting pair it reports, run on that pair; re-run over the touched set after each resolution until the verdict is .
- Append the spec to the end of the section (specs are chronological; new ones go last).
- Read the file again to confirm correct placement and syntax.
Rules
Complexity Limit
Each functional spec must imply a
maximum of 200 changed lines of code. If the requirement is too large, use the
skill to split it into multiple smaller, independent specs. Do not include LOC estimates in the spec text.
Chronological Ordering
Specs are rendered incrementally, top to bottom. The renderer has no knowledge of future specs — only previously rendered specs are in context. This means:
- A new spec can reference behavior defined by earlier specs.
- A new spec cannot assume anything about specs that come after it.
- Place the new spec at the correct position if it must come before a future spec; otherwise append at the end.
Language Agnosticism
Write in terms of behavior, concepts, and domain logic — not implementation constructs. Avoid language-specific types, generics syntax, framework annotations, or other constructs tied to a particular language or framework. General technical terms (null values, JSON types, HTTP status codes) are fine. Language-specific guidance belongs in
***implementation reqs***
.
No Conflicts
The new spec must not contradict any existing functional spec. Conflicting specs are the most costly outcome. Before adding, review all existing specs and verify the new one is compatible. Use
to check the new spec against every existing spec in
one batched call — it lists every conflicting pair, so a pair-by-pair analyzer is not needed. If ambiguity exists, add explicit detail to eliminate any conflicting interpretation. For each conflicting pair the batched analyzer reports, use the
skill to diagnose and fix it before proceeding.
Disambiguation
Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If a single line is not enough to fully disambiguate the behavior, use nested sub-bullets to add detail. Nested lines clarify the parent spec; they do not introduce separate functionality. Even with nested detail, the spec must still imply ≤ 200 LOC.
plain
- :User: should be able to send a :Message: to a :Conversation:.
- A :Message: must have non-empty content.
- The :Message: is appended to the end of the :Conversation:.
- All :Participant: members of the :Conversation: can see the new :Message:.
Deterministic Interface
Specs must be detailed enough that a developer can use the built software without reading the generated code. All external interfaces must be explicit — REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc. Never leave interface details up to the renderer's discretion.
Encapsulation
Functionality must be self-contained in the spec text.
modules only import functional specs, so do not rely on implementation reqs to convey behavior — they won't be visible in downstream modules.
Acceptance Tests
If the functional spec needs verification, use the
skill to add acceptance tests after inserting the spec.
Validation Checklist