add-implementation-requirement

Add Implementation Requirement

Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.

Workflow

1. Identify the target .plain file. If ambiguous, ask the user.
2. Read the file to understand existing implementation reqs, definitions, and functional specs.
3. Determine if this belongs in implementation reqs — it must describe HOW to build, not WHAT to build (that goes in ***functional specs***).
4. Draft the requirement following the rules below.
5. Insert it into the ***implementation reqs*** section.
6. Read the file again to confirm correct placement and syntax.

What Belongs Here

Implementation reqs are free-form instructions that steer code generation. Common contents:

• Technology choices: language, framework, runtime version
• Architectural constraints: patterns, layering, dependency rules
• Coding standards: naming conventions, style guidelines
• Data formats: serialization, encoding, transformation rules
• Error handling: strategies, retry logic, exception hierarchies
• Algorithm descriptions: specific approaches when behavior alone is insufficient
• Performance guidance: memory constraints, streaming requirements, batching strategies
• Language-specific constructs: generics, annotations, framework-specific types and idioms

What Does NOT Belong Here

• Behavior and features — those go in ***functional specs***
• Concept definitions — those go in ***definitions***
• Conformance-test instructions — those go in ***test reqs***. Note: unit-test instructions belong HERE, not in ***test reqs*** — see Unit-test guidance belongs here below

Unit-test guidance belongs here

Everything about :UnitTests: goes in ***implementation reqs*** — paths, approach, packages, framework (JUnit / pytest / Jest / Go's testing / …), conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates. Unit tests are part of the generated codebase, so requirements that shape them are implementation reqs by definition.

• The unit-test generator reads only ***implementation reqs***; anything about :UnitTests: placed in ***test reqs*** is silently ignored
• Phrase each :UnitTests: requirement in terms of the predefined :UnitTests: concept so the partition stays visible at a glance
• ***test reqs*** is exclusively for :ConformanceTests: — see add-test-requirement

Key Principle: HOW vs WHAT

***implementation reqs*** describe HOW the software should be built. ***functional specs*** describe WHAT the software should do.

If the requirement describes observable behavior (endpoints, business rules, user-facing features), it belongs in functional specs. If it describes internal structure, technology, or coding guidance, it belongs here.

Format

Implementation reqs are bullet points in the ***implementation reqs*** section:

***implementation reqs***
- :Implementation: should be in Python 3.12.
- :Implementation: should use pip for dependency management.
- When writing CSV files, :Implementation: should use streaming writes to avoid holding large datasets in memory.

Reference defined :Concepts: where they add clarity. Implementation reqs in non-leaf sections apply to all subsections.

Line syntax (hard rule)

Every line inside a section must be its own list item starting with - . ***plain has no concept of bare continuation lines — indented prose without a leading - is invalid syntax and the renderer will reject it.

• Hard limit: 120 characters per line. If a sentence is too long, split it at a natural clause boundary into nested - bullets — never wrap onto an unprefixed line.
• Nested detail is also a - item, indented under its parent. The indentation alone is not enough; the leading - is required.

BAD — bare continuation lines (invalid ***plain syntax, will not render):

- :Implementation: tech stack will be finalized in Phase 2.
  - Until then, treat this section as a placeholder so the renderer accepts
    the file. Phase 2 will replace this with language, framework, HTTP
    client, packaging, and architecture decisions.

GOOD — every line starts with - :

- :Implementation: tech stack will be finalized in Phase 2.
  - Until then, treat this section as a placeholder so the renderer accepts the file.
  - Phase 2 will replace it with language, framework, HTTP client, packaging, and architecture decisions.

Encapsulation Warning

requires modules only receive functional specs from their dependencies — not implementation reqs. If downstream modules need certain behavior to be visible, that behavior must be expressed in functional specs, not here.

Validation Checklist

• Describes HOW to build, not WHAT to build
• All referenced :Concepts: are defined in ***definitions***
• Does not duplicate guidance already present in the file or its imports
• Placed inside a ***implementation reqs*** section
• No behavioral requirements that should be in ***functional specs***