synaptiai/generating-constrained-specs

Constrained Spec Generation

This skill generates PRD and architecture documents that are constrained by the decision ledger.

Core Principle

No spec section without a DEC- reference.*

Every requirement, every architecture choice, must trace back to an explicit decision. This prevents:

• Ungrounded requirements
• Hidden assumptions
• Scope creep
• Orphaned features

Prerequisites

• Decisions complete (/ledger-decide)
• 04-decisions/DECISIONS.yaml exists
• 05-risks/RISKS.yaml exists

Workflow

Use TodoWrite to track these mandatory steps:

<required> 1. Load decisions and risks 2. Generate PRD with decision citations 3. Validate PRD constraint gate 4. Generate architecture with decision citations 5. Validate architecture constraint gate 6. Cross-reference risks in both documents </required>

Step 1: Load Decisions and Risks

Read:

• 04-decisions/DECISIONS.yaml - All decisions
• 05-risks/RISKS.yaml - All risks
• 03-synthesis/CROSS-SYNTHESIS.md - Context

Build decision index for quick lookup.

Step 2: Generate PRD

Write 06-prd/PRD.md using template from references/prd-template.md.

Constraint enforcement: Every section heading must include decision reference:

## 2. Target Users (DEC-scope-power-users-first)

Every requirement must cite decisions:

### 2.1 Primary Users
Power users within SMB organizations who manage complex workflows.
(DEC-scope-power-users-first, DEC-scope-smb-segment)

Step 3: Validate PRD Constraint Gate

Check every PRD section:

• [ ] Section heading has DEC-* reference
• [ ] Requirements cite supporting decisions
• [ ] Risks are cross-referenced where relevant

Gate failure: If any section lacks DEC-* reference, cannot proceed.

Step 4: Generate Architecture

Write 07-architecture/ARCHITECTURE.md using template from references/architecture-template.md.

Constraint enforcement:

## 3. Data Model (DEC-tech-postgres-primary, DEC-scope-power-users-first)

### 3.1 Core Entities
Based on power user workflow requirements (DEC-scope-power-users-first),
the data model supports complex nested structures.

Step 5: Validate Architecture Constraint Gate

Check every architecture section:

• [ ] Section heading has DEC-* reference
• [ ] Technical choices cite supporting decisions
• [ ] Risks are cross-referenced where relevant

Step 6: Cross-Reference Risks

In both documents, note relevant risks:

### Risk Note
This approach carries RISK-tech-cold-start. See risk register for mitigations.

Constraint Rules

See references/constraint-rules.md for detailed rules.

Citation Format

Section headings:

## 2. MVP Scope (DEC-scope-power-users-first, DEC-scope-web-only)

Inline citations:

Users will access the application via web browser only. (DEC-scope-web-only)

Evidence when needed:

Based on user research showing 78% onboarding drop-off at team invitation
(EV-users-onboarding-dropoff), we will simplify the invitation flow.
(DEC-ux-simplified-onboarding)

<good-example> ```markdown ## 2. Target Users (DEC-scope-power-users-first)

Based on DEC-scope-power-users-first, the MVP targets power users within organizations who manage complex workflows. This decision was supported by evidence showing 3x higher retention among power users (EV-users-retention-power-users).

2.1 User Needs

• Complex workflow management (DEC-scope-power-users-first)
• Keyboard-first interaction (DEC-ux-keyboard-shortcuts-priority)

Risk: RISK-retention-expert-churn mitigated by advanced feature set.

- Section heading cites DEC-* reference
- Every requirement traces to a decision
- Evidence cited where relevant
- Risks cross-referenced
</good-example>

<bad-example>
```markdown
## 2. Target Users

We will target power users because they are important. Power users need
features like advanced workflows and keyboard shortcuts.

### 2.1 User Needs
- Complex workflow management
- Keyboard-first interaction

• No DEC-* citation in heading
• No evidence supporting claims
• No traceability to decisions
• No risk acknowledgment </bad-example>

What Cannot Be Spec'd

• Features not supported by any decision
• Requirements contradicting decisions
• Architecture choices without technical decisions
• Scope outside decision boundaries

User Interaction

Use the AskUserQuestion tool when:

Missing decision for section

Question: "PRD section '[X]' has no supporting decision. How to proceed?"
Options:
- "Skip this section (out of scope)"
- "Make a new decision for this"
- "It relates to existing decision [DEC-Y]"

Decision conflict

Question: "Requirement '[X]' seems to conflict with [DEC-Y]. How to resolve?"
Options:
- "Revise requirement to align with decision"
- "The decision should be revisited"
- "They don't actually conflict - explain how"

Risk acknowledgment

Question: "This section relates to [RISK-X]. Include risk note?"
Options:
- "Yes, note the risk"
- "No, not relevant here"
- "Yes, and add mitigation detail"

Output

After spec generation:

## Spec Generation Complete

**PRD Sections:** [N] (all constrained)
**Architecture Sections:** [M] (all constrained)
**Decisions Referenced:** [X] unique DEC-* IDs
**Risks Cross-Referenced:** [Y] RISK-* IDs

### Constraint Gate Status
- PRD gate: ✓ All sections cite decisions
- Architecture gate: ✓ All sections cite decisions

### Documents Generated
- `06-prd/PRD.md`
- `07-architecture/ARCHITECTURE.md`

### Decision Coverage
| Decision | PRD Sections | Arch Sections |
|----------|--------------|---------------|
| DEC-scope-power-users-first | 1, 2, 4 | 2, 3 |
| DEC-pricing-freemium | 3, 5 | 4 |
| DEC-tech-serverless | - | 1, 3, 5 |
| ... | ... | ... |

### Next Step
Run `/ledger-plan` to generate implementation backlog.

References

• references/prd-template.md - PRD template
• references/architecture-template.md - Architecture template
• references/constraint-rules.md - Detailed constraint rules