Pending: Complexity threshold — which FRs require a design?
Pending: Review process — user approval only or also self-review checklist?
User Tasks
Summary
A structured workflow for creating, reviewing, and approving design documents before implementing complex features.
Problem / Motivation
vault/00_system/designs/drafts/ and approved/ directories exist but no process governs the lifecycle.
Complex FRs (agents, scheduler, state machine, orchestration) need upfront design to avoid rework.
Without a gate, designs will either be skipped (leading to poor implementation) or pile up unreviewed in drafts/.
The user wants to understand and approve architectural decisions before code is written.
Proposed Solution
A /design skill that generates a design document for a given FR into designs/drafts/. The user reviews it, and an /approve-design skill moves it to designs/approved/. Implementation of the FR is gated on an approved design (for FRs that require one).
Enforcement rules (to be added to path-scoped rules or CLAUDE.md when implemented)
Designs always go to designs/drafts/, never directly to approved/.
Never implement an FR that has an associated design doc until that doc is moved to approved/ by the user.
FRs with an associated design doc must have REQ-0 | Design doc reviewed and approved in their prerequisites.
Open Questions
1. Which FRs Need Designs?
Question: What’s the threshold for requiring a design document?
Option
Description
A) Phase count ≥ 3
FRs with 3+ phases are complex enough to warrant a design
B) Priority-based
Only high/critical priority FRs
C) Manual tag
FR author adds needs-design: true to frontmatter
D) Complexity score
Use FR-038 complexity routing score (once available)
Recommendation: Option C for now — explicit is better than implicit. Option D when FR-038 exists.
Decision:
2. Design Document Content
Question: What should a design document contain?
Option
Description
A) Architecture + trade-offs + API sketch
Enough to evaluate the approach without reading code
B) Full technical spec
Detailed implementation plan with pseudocode
C) Lightweight summary
Just the key decisions and their rationale
Recommendation: Option A — enough depth to catch bad decisions, not so much that it becomes a spec.
Decision:
Phase Overview
Phase
Description
Status
Phase 1
Design template + /design skill
—
Phase 2
/approve-design skill + FR frontmatter gate
—
Phase 3
Auto-detect FRs needing design (integrate with complexity routing)
—
Phase 1: Design Template & Skill —
Goal: Create a design document template and a skill to generate drafts.
File / Feature
Details
Owner
Status
vault/_templates/design.md
Design document template
opus
—
.claude/skills/design/SKILL.md
/design FR-XXX generates a design draft
opus
—
vault/00_system/designs/drafts/
Output directory (exists)
opus
done
Phase 2: Approval Flow —
Goal: Formalize the review and approval process.
File / Feature
Details
Owner
Status
.claude/skills/approve-design/SKILL.md
Move draft → approved, update FR frontmatter
opus
—
FR frontmatter field
design: draft/approved/not-required
opus
—
Implementation gate
Check for approved design before starting implementation
opus
—
Phase 3: Auto-Detection —
Goal: Automatically flag FRs that need a design but don’t have one.
File / Feature
Details
Owner
Status
Complexity check
Flag FRs with 3+ phases and no design
opus
—
Integration with FR-038
Use complexity score when available
opus
—
Dashboard warning
Surface “needs design” in feature dashboard
opus
—
Test
Manual tests
Test
Expected
Owner
Actual
Last
Run /design FR-067
Design draft created in designs/drafts/
mv
pending
-
Run /approve-design FR-067
Design moved to designs/approved/, FR updated
mv
pending
-
Try to implement FR with design: draft
Warning that design isn’t approved
mv
pending
-
AI-verified tests
Scenario
Expected behavior
Verification method
…
…
…
E2E tests
Scenario
Assertion
…
…
Integration tests
Component
Coverage
…
…
Unit tests
Component
Tests
Coverage
…
…
…
History
Date
Event
Details
2026-03-12
Created
Identified as gap — designs/ structure exists but no workflow
References
vault/00_system/designs/ — drafts/ and approved/ directories
FR-038 (Complexity Routing) — can feed complexity score to auto-detect
FR-043 (Approve & Implement Skills) — related approval pattern