Skip to main content

Specification Compilation: Hybrid Workflow

Category: Guidelines
Status: Draft (Awaiting Approval)
Scope: Standardizing how functional specifications are compiled, reviewed, and finalized.

🎯 Objective​

To define a clear methodology for choosing the right specification format (Gherkin vs. Use Case) and managing the "Verification Gate" between AI/Developer interpretations and Reality.

⚖️ Format Selection Matrix​

Logic TypeTarget FormatWhy?
Hidden LogicGherkin (.feature)Best for complex state transitions, math/logic calculations, and automated regression potential.
User WorkflowUse Case (.md)Best for describing human interaction steps, screen navigation, and administrative procedures.
Logic MappingMapping (.mapping.md)Best for traceability between Gherkin scenarios and specific legacy codebase references.

🏗️ Folder Structure​

docs/architecture/specs/
├── draft/             <-- Work-in-progress, unverified files
│   └── [module]/
├── current/           <-- Verified Single Source of Truth
│   └── [module]/
│       ├── dashboard_logic/  <-- Gherkin Files
│       └── user_tasks/       <-- Use Case Files
└── proposals/         <-- Major functional changes (Drafts)

🚀 The Compilation Workflow​

1. Investigation​

  • Analyze the codebase for a specific feature (e.g., "Student Refund").
  • Identify all Transition states and Business Rules.

2. Compilation (Draft)​

  • Generate the initial .feature or .md file in specs/draft/[module]/.
  • Mandatory Header for AI-Generated content:

    [!WARNING] AI-GENERATED DRAFT This specification is an interpretation of existing code. It has not yet been verified against domain expert knowledge.

3. Review & Verification​

  • Domain experts (Lead Dev/Creator) review the draft.
  • Discrepancies between what the code does and what the business wants are documented.
  • Decision Needed: Does the code match the intent?
    • Yes: Proceed to Finalization.
    • No: Document as a Bug or Logic Gap in the spec.

4. Finalization​

  • Relocate verified files to specs/current/[module]/.
  • Remove the "Draft" warning.
  • Update metadata.json for discovery.

🔗 Traceability Standard​

Every specification must maintain a link to its technical implementation.

  • Gherkin: Use [Tags] like @Code:OrderController:Save
  • Use Case: Include a Technical Implementation section at the end.

Reference: Functional Strategy