Skip to content

STANDARD-112: Module & Feature Specification Template

Status: Active / Golden Version: 3.0 (Comprehensive Architecture) Location: architecture/GOLDEN/DESIGN_SPECS/[NODE_ID].[INDEX]_[DOMAIN]_[FEATURE].md

[!IMPORTANT] This template ensures Architectural Persistence. It prevents the "Reinvention of the Wheel" by forcing alignment with established platform models (Persona, Capability, Forensic Arc).

0. Metadata & Platform Alignment

  • Target Domain: [e.g. 03. Domain Atlas / Directory]
  • Logical ID: [e.g. 03.2 - Feature Name]
  • Architectural Parent: 03_DOMAIN_ATLAS.md
  • Persona Impact: [Cite Persona(s) from 01_B_PERSONA_BOOK]
  • Capability Target: [Cite @cap ID(s) from 06_B_CAPABILITY_MATRIX]
  • Intuition Log: [Link to entry in architecture/THINKING/]

1. Executive Intent & Scope

  • Mission Statement: One-sentence goal for this specification.
  • The Forensic Why: Which specific accountability or agency is being codified?
  • Scope Boundaries:
    • IN SCOPE: [Item 1, Item 2]
    • OUT OF SCOPE: [Item 1, Item 2] (Crucial for preventing gold-plating).

2. Canonical Analysis & Models

Select the models that apply to this use case. Do not invent new analysis patterns.

2.1 The Forensic Arc (Narrative)

  • Actor (Who): [Linked Persona]
  • Subject (What): [The Physical/Legal Entity]
  • Mandate (Why): [Governance Rule/Legal Requirement]
  • Signal (When): [The resulting Telemetry event]

2.2 Data Interaction Model

  • Pivot Logic: Does this use the Multidimensional Pivot Directory (MPD)?
  • Relationship Density: Define One-to-Many vs. many-to-many paths.
  • State Machine: [Describe transitions if applicable, e.g. Draft -> Verified -> Archived].

3. Aesthetic & Interaction Logic

  • Pattern Compliance: [e.g. STND-60 Tri-Pane, STND-63 Hub-and-Spoke].
  • Key Transitions: (e.g., Bloom, Rubik's Rotation, Ghost-Fade).
  • High-Fidelity Mockups: Caption

4. Technical Blueprint

  • Zod Schemas: (The "Public Truth" DTOs).
  • Server Actions: [Detailed method signatures].
  • i18n Namespace: [e.g. directory.cortex].

5. Verification Blueprint (Standard 102)

  • Success Scenario: [Persona] performs [Action] and observes [Forensic Signal].
  • Boundary Hazards: What are the 2-3 most likely failure points?
  • Automated Gates: Required Vitest (Logic) and Playwright (Interaction) targets.

6. Post-Execution Reconciliation (Trailing Update)

This section is updated AFTER implementation and testing to capture "As-Built" deviations and educational primers.

  • Implementation Realizations: What did we discover during the "Actual" build? (e.g. state management trade-offs).
  • Verification Insights: What did the tests teach us about the edge cases?
  • NotebookLM Primer Readiness: Summarize the "Mastery" logic for extraction into educational multimedia.
  • Thinking Stash Reference: Final link to the codified [03.1_CORTEX_PHILOSOPHY.md].

🎓 The "What Good Looks Like" Checklist

✅ Strategic Rigor

  • [ ] Persona Alignment: Linked to a specific persona in 01_B_PERSONA_BOOK.md.
  • [ ] Capability Traceability: Every proposed action maps to a code in 06_B_CAPABILITY_MATRIX.md.
  • [ ] Intuition Preservation: Logic is stashed in architecture/THINKING/.

✅ Aesthetic Fidelity

  • [ ] Standard UI Patterns: Uses established platform components (Forensic Glass, Tri-Pane).
  • [ ] Visual Proof: Spec contains high-fidelity mockups or explainers.
  • [ ] Motion Clarity: Animation behavior is described (Transitions, Timing).

✅ Operational Readiness

  • [ ] i18n Included: Translation requirements are identified.
  • [ ] Telemetry defined: The resulting "Forensic Signal" is named and mapped.
  • [ ] Error Hygiene: Failure states use the AppError protocol.

🏁 The "Complete" Checklist (Execution Gate)

  • [ ] Saved in architecture/GOLDEN/DESIGN_SPECS/ with context-linking ID.
  • [ ] Reference added to 03_DOMAIN_ATLAS.md or relevant Parent Node index.
  • [ ] Media archived in DESIGN_SPECS/media/.
  • [ ] [walkthrough.md] created in brain with visual evidence.