Problem
technical_design.md.template contains several sections that duplicate information available elsewhere, causing version drift and unnecessary context consumption when loaded by LLM agents.
Specific Issues
1. ## Feature section — redundant
The Feature section lists feature files. This is already available from product_definition.md delivery order and the filesystem (ls docs/features/).
Action: Remove ## Feature section entirely.
2. ## Active Constraints section — redundant
Active constraints duplicate what is already stated in product_definition.md Quality Attributes with equal or greater specificity.
Action: Remove ## Active Constraints section entirely. Constraints belong in product_definition QA table or in individual ADRs.
3. Version columns in Stack and Dependencies — drift risk
The Version column in both tables drifts relative to pyproject.toml. Example: pytest >=9.0.3 in the doc vs >=8.3.5 in pyproject.toml.
Action: Remove Version columns. Add a note: "Version constraints in pyproject.toml are the source of truth."
4. Interface Definitions — no distinction between implemented and planned
The template puts all interfaces inline. Once implemented, these duplicate source code and will drift.
Action: Split into two sub-sections:
- Implemented — See Source Code: a table mapping interface name to source file path
- Planned — Not Yet Implemented: inline Python stubs (the contract-first spec)
As modules are implemented, move entries from Planned to Implemented.
5. Runtime/Development split in Dependencies — unnecessary
Splitting dependencies into sub-sections adds structure that pyproject.toml already provides.
Action: Single flat table with rationale only (no versions).
Proposed Template Structure
- Architectural Style (keep)
- Quality Attributes (keep)
- Stack (keep, remove version column, add pyproject.toml note)
- Module Structure (keep)
- API Contracts (keep)
- Event Contracts (keep)
- Interface Definitions (split into Implemented table + Planned stubs)
- C4 Diagrams (keep)
- Key Decisions (keep)
- Dependencies (single table, no versions, add pyproject.toml note)
- Configuration Keys (keep)
- Changes (keep)
Removed: ## Feature, ## Active Constraints
Problem
technical_design.md.templatecontains several sections that duplicate information available elsewhere, causing version drift and unnecessary context consumption when loaded by LLM agents.Specific Issues
1.
## Featuresection — redundantThe Feature section lists feature files. This is already available from product_definition.md delivery order and the filesystem (
ls docs/features/).Action: Remove
## Featuresection entirely.2.
## Active Constraintssection — redundantActive constraints duplicate what is already stated in product_definition.md Quality Attributes with equal or greater specificity.
Action: Remove
## Active Constraintssection entirely. Constraints belong in product_definition QA table or in individual ADRs.3. Version columns in Stack and Dependencies — drift risk
The Version column in both tables drifts relative to
pyproject.toml. Example: pytest >=9.0.3 in the doc vs >=8.3.5 in pyproject.toml.Action: Remove Version columns. Add a note: "Version constraints in
pyproject.tomlare the source of truth."4. Interface Definitions — no distinction between implemented and planned
The template puts all interfaces inline. Once implemented, these duplicate source code and will drift.
Action: Split into two sub-sections:
As modules are implemented, move entries from Planned to Implemented.
5. Runtime/Development split in Dependencies — unnecessary
Splitting dependencies into sub-sections adds structure that pyproject.toml already provides.
Action: Single flat table with rationale only (no versions).
Proposed Template Structure
Removed:
## Feature,## Active Constraints