PRD-CE methodology engine: scaffold (PRD/SoT/EPICs) + lifecycle skills + governance hooks + readiness scoring.
- GitHub stars
- 179
Install
/plugin install prd-ce@prd-ce-methodologyRun it inside Claude Code after adding the marketplace with /plugin marketplace add mattgierhart/PRD-driven-context-engineering.
Contents
Discovered from sourceSkills 50
[Skill Name]
[One sentence summary of the skill's purpose.]
Workflow Overview
- Step 1 → Brief description
- Step 2 → Brief description
- Step 3 → Brief description
Core Output Template
[Define the primary output structure this skill produces]
| Element | Definition | Evidence |
|---|---|---|
| Field 1 | What this captures | How to validate |
| Field 2 | What this captures | How to validate |
See assets/output-template.md for copy-paste template.
Step 1: [First Major Step]
[Detailed instructions for this step]
Checklist
- Item 1
- Item 2
Step 2: [Second Major Step]
[Detailed instructions for this step]
Step 3: [Third Major Step]
[Detailed instructions for this step]
Quality Gates
Pass Checklist
- Gate 1: [Specific, measurable criterion]
- Gate 2: [Specific, measurable criterion]
- Gate 3: [Specific, measurable criterion]
Testability Check
- Can this output be validated?
- Does it reference IDs from SoT/?
How this is evaluated: This skill's output is scored by
scripts/readiness.py(a deterministic, $0, no-LLM proxy). Clearing a gate is permission to advance, not the goal — the goal is evidence. Padding inputs to move the score without moving the evidence is a frozen-replay defect. SeePRINCIPLES.mdP7.
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Bad pattern 1 | "Example" | → "Better approach" |
| Bad pattern 2 | "Example" | → "Better approach" |
| Evidence fabrication | Back-filling confidence/evidence to clear a gate | → Cite a real source or mark the gap; never invent to pass (P4 anti-leakage, P7) |
Bundled Resources
references/[file].md— [Description of when to use]assets/[template].md— [Description of template purpose]
Handoff
[What happens after this skill completes? What stage/skill comes next?]
Gate Check
Validate whether the PRD stage is ready to advance to the next version. Delegates to the three-layer readiness scorer — SoT files → EPICs → stage — then surfaces the leverage view (what to fix first, and which EPICs it unblocks).
Workflow Overview
- Compute → run
scripts/readiness.py run --quietto refreshstatus/readiness.json - Read → parse
status/readiness.json - Report → PASS / WARN / BLOCK verdict with top blockers and causal links
- Recommend → actionable next steps (always highest-leverage first)
Authority
references/gate-criteria.md remains the canonical source of mandatory artifacts per gate. The scorer's GATE_REQUIREMENTS table mirrors it. Do not hand-roll checklists here — the scoring engine is the single source of truth.
Step 1: Compute
Run the orchestrator. It runs SoT → EPIC → stage in dependency order and writes status/readiness.json.
python scripts/readiness.py run --quiet
# exit 0 = all pass, 1 = warn, 2 = block, 3 = error
If the exit code is 3, report a runtime error and stop. If 0/1/2, proceed to Step 2.
Fallback: no scripts available
If scripts/readiness.py is missing or Python is unavailable, fall back to reading status/readiness.json directly. If that's also absent, report: "Readiness not yet computed — install scripts/requirements.txt and run python scripts/readiness.py run."
Step 2: Read
cat status/readiness.json
Extract:
summary.current_stage— the gate being evaluated and its scoresummary.top_blockers— ranked SoT files blocking progressstages.{target}— detailed stage block (dimensions, unmet_criteria, caps)epics.{id}— per-EPIC scores (cite the lowest ones)
Step 3: Report
Use this template. Fill every field from the JSON — do not improvise scores.
## Gate Check Report: {stage.gate_description}
**Verdict**: [PASS | WARN | BLOCK]
**Stage Score**: {stage.score} / 100 (warn < {threshold_warn}, block < {threshold_block})
**Date**: {now}
### Stage Dimensions
| Dimension | Score | Weight |
|-----------|-------|--------|
| required_ids_present | {score} | {weight} |
| relevant_sot_readiness | {score} | {weight} |
| cross_ref_integrity | {score} | {weight} |
| downstream_epic_readiness | {score or "n/a"} | {weight or "—"} |
### Top Blockers (leverage view)
1. **{file}** (score {score}) — blocks {N} EPICs: {EPIC-XX, …} — impact {impact}
2. …
### Unmet Criteria (high severity first)
- [high] {ref}: {reason}
- [medium] {ref}: {reason}
### Recommendation
**If PASS**: Advance to {next_version}. Run `ghm-status-sync` to update the README dashboard.
**If WARN / BLOCK**: Do not advance. Address top blockers in order — fixing the highest-impact SoT file cascades up the graph.
**Next action**: {top_blockers[0] → concrete fix}
Verdict bands
| Stage score | Verdict | Meaning |
|---|---|---|
| ≥ 70 | PASS | Safe to advance |
| 50–69 | WARN | Advance with documented risk; log in PRD change log |
| < 50 | BLOCK | Cannot advance — per rule 05-lifecycle-gates, update the EPIC and STOP |
Step 4: Recommend
Always prioritize by impact = (100 − score) × #EPICs blocked. The top blocker is the single highest-leverage fix; cite its blocking_epics list so the human understands what unblocks.
Quality Gates
- Stage score cited from JSON, not estimated
- Top blockers include their consumer EPICs
- Recommendation is actionable (specific file, specific action)
- Verdict matches the score band exactly (don't round up)
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Ignoring the score | "Feels ready; pass" | Cite stage.score verbatim |
| Skipping blockers | "Minor stuff, advance anyway" | Block if score < 50; warn if < 70 |
| Hand-rolling criteria | Re-checking IDs manually | Trust the scorer; if wrong, fix GATE_REQUIREMENTS in _readiness/stage.py |
| Forcing PASS | Overriding the verdict | Never override; the score is the contract |
Boundaries
DO:
- Delegate computation to
readiness.py - Cite specific scores, files, and EPICs from the JSON
- Surface the
top_blockersleverage view
DON'T:
- Modify
status/readiness.jsondirectly — it's computed output - Create missing artifacts inside this skill (that's the author's job)
- Override PASS/BLOCK verdicts subjectively
Handoff
After a report:
- PASS: Trigger
ghm-status-sync; the gate advancement updates the README dashboard - WARN: Same as PASS but note the risks in the PRD change log
- BLOCK: Return control to the human. The
top_blockers[0]fix is the single most important next action
References
references/gate-criteria.md— canonical gate requirements (consumed by scorer)references/examples.md— pass/warn/block report examples.claude/rules/07-readiness-protocol.md— the discipline ruledocs/READINESS_PROTOCOL.md— full schema
Harvest
Extract durable insights from temporary files to Source of Truth during EPIC Phase E (Finish).
Workflow Overview
- Enumerate Temps → List all temp/ files from current EPIC
- Identify SoT-worthy → Determine what should persist
- Format Entries → Convert to proper SoT templates
- Archive → Move temps to archive, update manifest
Core Output Template
| Element | Definition | Evidence |
|---|---|---|
| Temp Files | Files processed | List with paths |
| New SoT Entries | IDs created | BR-XXX, UJ-XXX, etc. |
| Archive Manifest | What was archived | Paths and dates |
| Discarded | What was not kept | Reason for each |
Harvest Decision Matrix
| Content Type | Action | Destination |
|---|---|---|
| Business rule discovered | Extract | SoT/SoT.BUSINESS_RULES.md |
| User flow documented | Extract | SoT/SoT.USER_JOURNEYS.md |
| API design finalized | Extract | SoT/SoT.API_CONTRACTS.md |
| Customer feedback captured | Extract | SoT/SoT.customer_feedback.md |
| Session notes | Archive only | archive/YYYY-MM/ |
| Scratch work | Discard | Delete after review |
Step 1: Enumerate Temp Files
- Read EPIC Execution Plan for temp file references
- List all files in
temp/directory - Match temps to EPIC (by date or naming)
Checklist
- All EPIC-referenced temps identified
- Temp directory scanned
- Files categorized by content type
Step 2: Identify SoT-Worthy Content
For each temp file, evaluate:
| Question | If Yes | If No |
|---|---|---|
| Is this a business rule? | Extract as BR-XXX | Continue |
| Is this a user flow? | Extract as UJ-XXX | Continue |
| Is this an API design? | Extract as API-XXX | Continue |
| Is this customer evidence? | Extract as CFD-XXX | Continue |
| Is this useful context? | Archive | Continue |
| Is this scratch work? | Discard | - |
Checklist
- Each temp file evaluated
- Extract/Archive/Discard decision made
- Decisions documented
Step 3: Format SoT Entries
For each extracted item:
- Generate appropriate ID using
ghm-id-register - Format per SoT template
- Add cross-references
- Insert into correct SoT file
Entry Template
### [ID]: [Title]
**Status**: Active
**Created**: YYYY-MM-DD
**Source**: temp/[filename].md (EPIC-XX)
**Cross-References**: [Related IDs]
[Extracted content, properly formatted]
Checklist
- All extracts have valid IDs
- Formatting matches SoT templates
- Cross-references verified
Step 4: Archive and Cleanup
- Create archive directory:
archive/YYYY-MM/ - Move processed temps to archive
- Generate manifest
- Update EPIC Phase E checklist
Archive Manifest Template
## Archive Manifest: EPIC-XX
**Date**: YYYY-MM-DD
**Archived To**: archive/YYYY-MM/
### Extracted to SoT
| Temp File | New ID | SoT File |
|-----------|--------|----------|
| temp/file.md | BR-XXX | SoT.BUSINESS_RULES.md |
### Archived Only
| Temp File | Reason |
|-----------|--------|
| temp/notes.md | Session context |
### Discarded
| Temp File | Reason |
|-----------|--------|
| temp/scratch.md | No durable value |
Quality Gates
Pass Checklist
- All temps processed (none orphaned)
- Extracted content has valid IDs
- Archive manifest is complete
- EPIC Phase E checklist updated
Testability Check
- SoT entries are findable by ID
- Archive manifest matches actual files
- Temp directory is clean
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Orphan temps | Temps not in manifest | → Process all files |
| Lost context | Archive without manifest | → Always create manifest |
| Over-extraction | Everything becomes SoT | → Apply decision matrix |
| Under-extraction | Valuable insights lost | → Review before discard |
Boundaries
DO:
- Extract durable insights
- Format per templates
- Create complete manifests
- Clean up temps
DON'T:
- Create new analysis
- Modify conclusions
- Skip the manifest
- Delete without review
Handoff
After harvest completes:
- SoT files updated with new entries
- Temps archived with manifest
- EPIC Phase E marked complete
- Ready to close EPIC
ID Register
Validate and register new Source of Truth IDs with cross-reference integrity checks.
Workflow Overview
- Validate Format → Check ID follows
[PREFIX]-[3-digit]pattern - Check Uniqueness → Ensure ID doesn't already exist
- Verify Cross-Refs → All referenced IDs must exist
- Register Entry → Add to appropriate SoT file
Core Output Template
| Element | Definition | Evidence |
|---|---|---|
| ID | Unique identifier | BR-101, UJ-045, API-012 |
| Title | Short descriptive name | Clear, specific |
| Cross-References | Links to related IDs | All referenced IDs exist |
| Status | Current state | Draft / Active / Deprecated |
ID Format Reference
| Prefix | Domain | File |
|---|---|---|
BR- | Business Rules | SoT/SoT.BUSINESS_RULES.md |
UJ- | User Journeys | SoT/SoT.USER_JOURNEYS.md |
API- | API Contracts | SoT/SoT.API_CONTRACTS.md |
CFD- | Customer Feedback | SoT/SoT.customer_feedback.md |
Step 1: Validate Format
Check ID follows the pattern:
[PREFIX]-[XXX]
Where:
- PREFIX = BR, UJ, API, or CFD
- XXX = 3-digit number (zero-padded)
Checklist
- Prefix is valid (BR, UJ, API, CFD)
- Number is 3 digits
- Format matches
[A-Z]+-[0-9]{3}
Step 2: Check Uniqueness
- Read target SoT file
- Extract all existing IDs of same prefix
- Verify new ID doesn't exist
- If auto-assigning: use highest existing + 1
Checklist
- Target SoT file read
- Existing IDs enumerated
- New ID is unique
Step 3: Verify Cross-References
For each ID referenced in the new entry:
- Identify the prefix
- Check that ID exists in its SoT file
- Flag any missing references
Checklist
- All
BR-XXXreferences exist in BUSINESS_RULES - All
UJ-XXXreferences exist in USER_JOURNEYS - All
API-XXXreferences exist in API_CONTRACTS - All
CFD-XXXreferences exist in CUSTOMER_FEEDBACK - Each cross-reference includes a relationship type (see
references/cross-reference-patterns.md) - Relationship types match the directional hierarchy (vertical types for cross-layer, lateral types for same-layer)
Step 3.5: Evaluate Confidence (NEW)
Before registering, assign a confidence score (1-5) based on evidence strength:
| Score | Evidence Level | Examples |
|---|---|---|
| 1/5 | Assumption / PM decision | "We think users want X" |
| 2/5 | Secondary research | Competitive analysis, market report |
| 3/5 | Direct feedback | User interviews (3-5 conversations) |
| 4/5 | Validated behavior | Beta testing, small-scale usage |
| 5/5 | Production evidence | Real usage data at scale |
Question to ask: What's the highest evidence supporting this entry right now? What would move it to the next confidence level?
Example confidence annotations:
confidence: 2/5, source: competitive-analysisconfidence: 3/5, source: 5-user-interviews-jan-2026confidence: 4/5, source: beta-cohort-validation
See .claude/skills/PRINCIPLES.md for detailed confidence model by SoT type.
Checklist
- Confidence score assigned (1-5)
- Highest evidence source identified
- Forward path identified ("would move to X/5 if...")
Step 4: Register Entry
Add formatted entry to SoT file:
### [ID]: [Title]
**Status**: Draft
**Created**: YYYY-MM-DD
**Confidence**: [1-5]/5 (source: [evidence source])
**Next Confidence Target**: [What would move this to next level]
**Cross-References**: [List of related IDs]
[Description]
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
Example entry with confidence:
### CFD-042: Users want dark mode
**Status**: Active
**Created**: 2026-02-01
**Confidence**: 3/5 (source: 5-user-interviews-jan-2026)
**Next Confidence Target**: 4/5 (would require beta cohort validation)
**Cross-References**: FEA-008 (dark mode feature)
During interviews, 4 of 5 users mentioned desire for dark mode. Competitors (Notion, Linear, Figma) all have it.
**Acceptance Criteria**:
- [ ] Feature FEA-008 delivered to beta cohort
- [ ] Track usage: % of beta users enabling dark mode
Quality Gates
Pass Checklist
- ID format is valid
- ID is unique within its domain
- All cross-references resolve
- Entry follows SoT template
- Confidence score assigned (1-5) with source documented
- Next confidence target identified
Testability Check
- ID can be searched and found
- Cross-references are bidirectional (if required)
- Confidence score is honest (reflects actual evidence, not wishful thinking)
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Duplicate ID | Creating BR-101 when it exists | → Check uniqueness first |
| Orphan reference | References UJ-999 that doesn't exist | → Verify all cross-refs |
| Wrong prefix | Using BR- for an API contract | → Match prefix to domain |
| Missing zero-pad | BR-5 instead of BR-005 | → Always use 3 digits |
| Inflated confidence | Assigning 4/5 to a PM assumption | → Be honest about evidence level |
| No confidence source | "confidence: 3/5" with no source | → Always record source (CFD-001, user-interview-jan, etc.) |
| Missing confidence target | Confidence assigned but no forward path | → Ask "what would move this to 4/5?" |
Boundaries
DO:
- Format validation
- Uniqueness checks
- Cross-reference verification
- Entry formatting
DON'T:
- Content decisions about ID meaning
- Approve/reject based on business logic
- Modify existing IDs
Handoff
After ID registration:
- New ID is in SoT file
- Cross-references are valid
- EPIC Execution Plan updated with new ID
- Ready for implementation
Self-Install
Install the methodology into a target repo from the install manifest, the way Xantham's blueprint installs from markdown: the agent runtime is the installer, so the whole thing runs inside your Claude Code subscription — no API key, no metered calls, no service to stand up.
Two paths, one manifest. This skill is the interactive path.
install.shis the deterministic CLI path. Both read.claude/install-manifest.yaml, so they can't drift. Prefer drivinginstall.shfrom this skill; fall back to manual copies only when the script isn't reachable.
Consumes
.claude/install-manifest.yaml— authoritativeframework/template_seed/never_touchlists (the keystone; never hardcode file lists).install.sh— the deterministic installer this skill normally drives.- Safety rules from
ghm-template-syncPhase "Safety Rules" — never overwriteMEMORY.md,SoT/*,PRD.md,README.mdcontent.
Produces
- An installed framework in the target repo (no new SoT IDs — this skill places the engine, it doesn't author specs).
- A verification report (hooks emit valid JSON;
readiness.pyruns).
Workflow
Phase 1 — Preflight & mode detect
- Confirm
git,python3,awkare present; warn if the target isn't a git repo. - Detect mode: greenfield (no
.claude/) vs brownfield (existing.claude/). Brownfield means merge, never overwrite product. - State the trade explicitly: this installs files only — it costs subscription tokens for the wizard turn, zero API.
Phase 2 — Wizard questions
Ask only what changes the outcome (honor the execution mode's budget):
- Target directory (default: current repo).
- Domain profile:
product(default) ·library·infrastructure·research. - Subset
[standard+]: keep all 4 agents + all skills (default), or trim to a role subset. Quick mode skips this and installs everything.
Phase 3 — Install (drive install.sh)
Run the deterministic installer so behavior matches the CLI path exactly:
bash install.sh --target <DIR> --profile <PROFILE> # add --dry-run to preview
- Show the
--dry-runplan first[standard+], then execute. - If a framework file shows drift, surface the diff and only re-run with
--forceafter the user confirms (mirrorsghm-template-sync"show diff before destructive"). - Never write anything in the manifest's
never_touchlist.
Phase 4 — Verify (trust-but-verify, the Xantham verify-blueprint.sh analog)
- Run each
.claude/hooks/*.shin the target; assert valid JSON on stdout. - Run
python scripts/readiness.py run— a non-zero exit on an empty scaffold is the expected BLOCK gate (no content yet), not a failure. Report the score. - Print next steps: customize
README.md+PRD.md, then "Let's frame the problem".
Anti-patterns
| Pattern | Fix |
|---|---|
| Hardcoding the file list in the skill | Read .claude/install-manifest.yaml |
Overwriting a brownfield repo's PRD.md/SoT | Honor never_touch; seed templates once |
| Treating readiness BLOCK on a fresh scaffold as a bug | It's the gate working — report the score |
Re-implementing copy logic instead of driving install.sh | One code path = no drift |
SoT Builder
Create new Source of Truth files that fit your product's unique needs while maintaining template purity.
When to Use This Skill
This skill is for rare occasions (3-4 times per product lifecycle) when:
- You fork this repo and the existing SoT files don't cover your artifact types
- Your product needs to track a concept that doesn't fit existing ID prefixes
- You need to consolidate scattered documentation into a canonical SoT
Do NOT use when:
- An existing SoT file covers your need (just add entries there)
- You want to track temporary/session-specific data (use
temp/instead) - The artifact type is already covered by
ghm-id-register
Workflow Overview
- Identify Need → Confirm no existing SoT fits
- Design Schema → Define ID prefix, categories, required fields
- Draft Template → Create pure structure (no methodology teaching)
- Validate Purity → Apply the litmus test
- Register & Integrate → Update SoT.README.md and ID system
Core Output Template
See assets/sot-template.md for the copy-paste starter template.
| Element | Definition | Required |
|---|---|---|
| YAML Frontmatter | version, purpose, id_prefix, authority | Yes |
| Purpose Block | Single paragraph explaining what this tracks | Yes |
| Navigation Section | Category links for quick access | Yes |
| Entry Template | Repeatable structure for each ID | Yes |
| Cross-Reference Index | Bidirectional links to other SoT files | Yes |
| Update Protocol | When/how to add new entries | Yes |
Step 1: Identify the Need
Before creating a new SoT, verify:
Checklist
- Searched existing SoT files for similar artifact types
- Confirmed the concept is durable (survives multiple sessions)
- Confirmed the concept needs unique IDs for cross-referencing
- Confirmed this isn't better served by a subsection in an existing SoT
Questions to Answer
-
What artifact type does this track?
- Bad: "Notes" (too generic)
- Good: "Partner Integration Contracts" (specific, durable)
-
Why can't existing SoT files handle this?
- Valid: "We need different fields than API contracts for partner integrations"
- Invalid: "I just want a separate file" (preference, not need)
-
What ID prefix will you use?
- Must be unique across the system
- 2-4 uppercase letters
- Check
SoT/SoT.UNIQUE_ID_SYSTEM.mdfor existing prefixes
Step 2: Design the Schema
Define the structure before writing:
ID Prefix Selection
Format: [PREFIX]-[XXX]
Examples: PIC-001, INT-042, MIG-003
Rules:
- 2-4 uppercase letters
- Descriptive but short
- Unique across all SoT files
- Check existing prefixes in
SoT/SoT.UNIQUE_ID_SYSTEM.md
Category Ranges
Reserve ID ranges for logical groupings:
**Category A** (XXX-001 to XXX-099):
**Category B** (XXX-101 to XXX-199):
**Category C** (XXX-201 to XXX-299):
Required Fields per Entry
Define the minimum fields every entry needs:
| Field | Purpose | Example |
|---|---|---|
| ID | Unique identifier | PIC-001 |
| Title | Human-readable name | "Stripe Payment Integration" |
| Status | Current state | Active / Deprecated / Planned |
| Created | Origin date | 2025-01-10 |
| Last Updated | Last modification | 2025-01-15 |
| Related IDs | Cross-references | BR-101, API-045 |
Optional Fields
Add domain-specific fields as needed, but keep them structural (not methodology):
- Good: "Partner Contact" (data field)
- Bad: "Best Practices for Partner Selection" (methodology teaching)
Step 3: Draft the Template
Use assets/sot-template.md as your starting point.
Structure Sections
- YAML Frontmatter - Metadata for the file
- Title & Purpose Block - What this SoT tracks
- Navigation by Category - Quick links to entries
- Entry Template - Repeatable structure (copy for each new entry)
- Deprecated Section - Where old entries go
- Cross-Reference Index - Bidirectional links
- Update Protocol - When/how to maintain
Template Purity Rules
KEEP in the template (self-documentation):
- When to add new entries
- Required fields checklist
- Cross-reference integrity checks
- File-specific maintenance procedures
MOVE to skill references (methodology teaching):
- "Best practices" for this domain
- "What makes a good entry"
- Example workflows beyond format
- Evaluation criteria
Litmus Test
For each section, ask:
"Is this teaching me how to maintain the FILE STRUCTURE, or teaching me DOMAIN KNOWLEDGE about what makes good content?"
- File structure maintenance → Keep in template
- Domain knowledge → Move to skill references
Step 4: Validate Purity
Before finalizing, run this checklist:
Purity Checklist
- No "how to analyze" or "how to evaluate" content
- No "best practices" or "key learnings" sections
- No cross-file workflows (multi-file coordination)
- No "what makes a good entry" evaluation criteria
- Examples show FORMAT only, not instructional CONTENT
- Self-documentation is under 20% of total file size
Self-Documentation Checklist
- Has "Update Protocol" section
- Documents when to add new IDs
- Includes cross-reference integrity checks
- Specifies required fields for new entries
- Self-documentation is file-specific (not generic)
Context Efficiency Checklist
- Template can be read without loading other files
- Methodology examples are in skill references, not template
- General governance references SoT.README.md
Step 5: Register and Integrate
After creating the SoT file:
Update SoT.README.md
Add entry to the structure table:
| `SoT.{YOUR_FILE}.md` | {PREFIX}-### | {Purpose description} |
Update SoT.UNIQUE_ID_SYSTEM.md
Add new prefix to Section 1.2 Standard Prefixes:
| **{PREFIX}** | {Meaning} | `SoT.{YOUR_FILE}.md` |
Create Index Tables
Add empty index table in Part 2 of SoT.UNIQUE_ID_SYSTEM.md:
#### {Your Type} ({PREFIX}-XXX)
| ID | Title | Status | Used By |
|----|-------|--------|---------|
| {PREFIX}-001 | {Title} | Active | {IDs} |
Quality Gates
Pass Checklist
- ID prefix is unique across all SoT files
- Template follows purity standard
- Update protocol included
- Cross-reference index structure defined
- SoT.README.md updated
- SoT.UNIQUE_ID_SYSTEM.md updated
Testability Check
- Can create a new entry using only the template instructions
- Cross-references can be validated programmatically
- Entries can be found by ID search
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Methodology in template | "Best practices for partner selection" | Move to skill references |
| Duplicate prefix | Using BR- for a new file | Choose unique prefix |
| Too generic | "Notes.md" | Be specific: "Partner_Integrations.md" |
| No update protocol | Template with no maintenance section | Add "Update Protocol" section |
| Orphan SoT | Not registered in SoT.README.md | Always register new files |
Bundled Resources
references/sot-patterns.md— Common patterns across existing SoT filesreferences/examples.md— Before/after examples of SoT creationassets/sot-template.md— Copy-paste starter template
Handoff
After creating a new SoT:
- SoT file exists at
SoT/SoT.{NAME}.md - SoT.README.md lists the new file
- SoT.UNIQUE_ID_SYSTEM.md has the new prefix
- Ready to use
ghm-id-registerfor adding entries
Status Sync
Synchronize the README.md Command Center with the current project state after gate advancement or EPIC status changes.
Workflow Overview
- Load Context → Read README.md, PRD.md metadata, Active EPIC Session State section
- Extract State → Pull lifecycle stage, blockers, metrics
- Update Dashboard → Sync README sections with current truth
Core Output Template
| Element | Definition | Evidence |
|---|---|---|
| Lifecycle Stage | Current PRD version from PRD.md | Current Lifecycle Gate: v0.X |
| Gate Status | Visual progress indicators | 🟢 Complete / 🟡 In Progress / ⚪ Pending |
| Active EPIC | Current work from EPIC header | EPIC-XX: Title |
| Blockers | Open blockers from EPIC Session State section | List with severity |
Step 1: Load Context
Read these files in order:
README.md(current state)PRD.md(metadata block for lifecycle stage)- Active EPIC Session State section (blockers, progress)
Checklist
- README.md loaded
- PRD.md metadata extracted
- Active EPIC identified and Session State section read
Step 2: Extract Current State
Pull authoritative values:
| Field | Source |
|---|---|
| Lifecycle Stage | PRD.md Current Lifecycle Gate |
| Gate Progress | PRD.md gate table |
| Active EPIC | README.md Active Work section |
| Blockers | EPIC Session State section |
| Metrics | README.md Truth Table |
Step 3: Update README Dashboard
Apply synchronization rules:
- Lifecycle Stage: Update header to match PRD.md
- Gate Table:
- 🟢 = Passed gates (all criteria met)
- 🟡 = Current gate (in progress)
- ⚪ = Future gates (not started)
- Active EPIC: Update metadata in Active Work section
- Blockers: Sync from EPIC Session State section
- Squad Status (Section:
squad-status): Update agent and EPIC tables:- For each agent in
.claude/agents/: check MEMORY.md mtime for "Last Active", grep EPICs for agent name for "Current EPIC" - For each EPIC in
epics/: read State field, Epic Lead, and Change Log last date - Status values:
active(session <2h old),idle(no recent activity),blocked(blocker in session state)
- For each agent in
Quality Gates
Pass Checklist
- README lifecycle stage matches PRD.md
- Gate indicators are accurate (no 🟢 on incomplete gates)
- Active EPIC reference is current
- Blockers reflect actual state
Testability Check
- Can be validated by comparing README to PRD.md
- Gate status is traceable to gate criteria
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Stale gate status | 🟢 on gate with missing criteria | → Verify all criteria before marking complete |
| Missing blockers | EPIC has blockers, README shows none | → Always sync from EPIC Session State section |
| Wrong EPIC reference | README points to closed EPIC | → Check EPIC status before updating |
Boundaries
DO:
- Status synchronization
- Link updates
- Gate progression indicators
DON'T:
- Content changes to descriptions
- Create new sections
- Modify PRD.md (read-only source)
Handoff
After status sync completes:
- README.md is current and accurate
- Ready for next work session
- Gate-check skill can validate if advancing
Template Sync
Detect template version drift and migrate to the latest template version.
Workflow
Phase 1: Detect Current State
- Read
.claude/VERSION(if it exists) to get current template version - If no VERSION file, check
CLAUDE.mdfrontmatter fortemplate_version - If neither exists, assume v1.0.0 (pre-versioning)
- Report: "Your repo is on template v{X}. Latest is v{Y}."
Phase 2: Diff Against Template
Compare your repo structure against what the current template version expects:
Check for missing files:
.claude/VERSION.claude/domain-profile.yaml.claude/hooks/HOOK_CONTRACT.md.claude/hooks/context-validation.sh.claude/hooks/context-density-gate.sh.claude/hooks/sot-update-trigger.shCHANGELOG.mdMIGRATION.md
Check for stale files (should be removed):
.claude/hooks/context-validation.py.claude/hooks/context-density-gate.py.claude/hooks/sot-update-trigger.py.claude/agents/HORIZON.md(replaced by subdirectory).claude/agents/STUDIO.md.claude/agents/DEVLAB.md.claude/agents/METRO.md
Check for structure issues:
settings.json: Does it use 3-level nesting? Are timeouts in seconds?- Agent directories: Do
horizon/,studio/,devlab/,metro/subdirectories exist withAGENT.md+MEMORY.md? - EPIC template: Does it use semantic headers (not numbered)?
- Frontmatter: Do key files have
template_version?
Phase 3: Generate Migration Plan
Output a table:
| File | Status | Action | Risk |
|---|---|---|---|
.claude/VERSION | Missing | Copy from template | None |
.claude/hooks/*.py | Stale | Delete (replaced by .sh) | None |
.claude/agents/HORIZON.md | Stale | Split into horizon/AGENT.md + MEMORY.md | Preserve MEMORY.md content |
settings.json | Outdated | Update hook nesting + commands | Check for custom hooks |
CLAUDE.md | Missing frontmatter | Add template_version: "3.0.0" | None |
Phase 4: Execute Safe Updates
Auto-safe (do without asking):
- Create
.claude/VERSIONwith current template version - Add
template_versionfrontmatter to files that lack it - Report what was done
Confirm first (show diff, ask user):
- Update
settings.jsonhook configuration - Restructure agent files (must preserve MEMORY.md)
- Delete stale Python hooks
- Update EPIC template headers
Never touch (product-specific):
PRD.mdcontent (only add frontmatter)SoT/*.mdcontentepics/EPIC-*.mdcontent (only update headers on closed EPICs).claude/agents/*/MEMORY.mdcontentREADME.mdcontent
Phase 5: Verify
After all changes:
- Test all shell hooks produce valid JSON
- Verify no Python hooks remain
- Confirm
settings.jsonuses correct nesting - Check agent subdirectories have both AGENT.md and MEMORY.md
- Report summary of changes made
Version Migration Matrix
| From | To | Key Changes |
|---|---|---|
| v1.0.0 | v2.0.0 | Add skills, hooks, agents, SoT standardization |
| v2.0.0 | v3.0.0 | Shell hooks, agent subdirs, semantic EPICs, versioning, domain-profile |
| v1.0.0 | v3.0.0 | All of the above (cumulative) |
Safety Rules
- NEVER overwrite MEMORY.md -- these contain product-specific agent memory
- NEVER modify SoT content -- only add section markers or frontmatter
- NEVER modify PRD.md content -- only add frontmatter version
- ALWAYS show diff before destructive changes (deletes, restructures)
- ALWAYS verify hooks work after updating settings.json
- Commit changes incrementally -- one commit per phase, not one giant commit
/prd-ce:init — Greenfield Scaffold Seeder
Plant the consumer-owned scaffold for a fresh PRD-CE project. The methodology engine
(lifecycle skills, the agent squad, governance hooks, readiness.py) is delivered live
by the installed prd-ce plugin — it never gets copied into your repo. This skill seeds only
what is yours to own and edit: PRD.md, the SoT/ graph, epics/ templates, your
.claude/domain-profile.yaml, and per-agent MEMORY.md starters.
One manifest, no drift. The seed list comes from
install-manifest.yaml'stemplate_seedsection — the same listinstall.sh(fork path) andghm-template-sync(update path) read. This skill drives the deterministicprd-ce-init.shso behavior is identical no matter who invokes it.
Scope (v1): greenfield only. This seeds an empty structure into a fresh repo. Mid-build and live-codebase on-ramps (entry-mode branching, graph extraction) are backlogged — see
temp/plugin-conversion-plan.md. If the target already hasPRD.mdorSoT/content, the seeder keeps it (non-destructive) rather than adapting to it.
Consumes
${CLAUDE_PLUGIN_ROOT}/templates/— the bundled seed sources (mirrorstemplate_seedpaths) the packager ships with the plugin.install-manifest.yamltemplate_seed+never_touch— authoritative seed/skip lists.scripts/prd-ce-init.sh— the deterministic seeder this skill drives.
Produces
- A seeded scaffold in the target repo (no new SoT IDs — this skill places templates, it does not author specs).
- A freshly reset
PRD.md(frontmatter at v0.1, today's date, no staletemplate_version). - A verification report (hooks emit valid JSON;
readiness.pyruns).
Workflow
Phase 1 — Preflight
- Confirm
git,python3,bashare present. Warn (don't block) if the target isn't a git repo. - Confirm greenfield: if
PRD.mdor non-emptySoT/already exist, say so and stop — the seeder will keep them untouched, so there is nothing for init to do. (Point the user at the lifecycle skills to keep building, not at re-seeding.)
Phase 2 — Wizard questions
Ask only what changes the outcome (honor the execution mode's budget):
- Target directory (default: current repo).
- Domain profile:
product(default) ·library·infrastructure·research. Quick mode skips this and takes the default.
Phase 3 — Seed (drive prd-ce-init.sh)
Run the deterministic seeder so behavior matches every other path:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/prd-ce-init.sh" --target <DIR> --dry-run # preview
bash "${CLAUDE_PLUGIN_ROOT}/scripts/prd-ce-init.sh" --target <DIR> # seed
- Show the
--dry-runplan first[standard+], then execute. - The seeder skips any file that already exists (
never_touchhonored) and resets a freshly seededPRD.mdfrontmatter to v0.1. - After seeding, if the chosen domain profile differs from the default, update the
profile:key in the seeded.claude/domain-profile.yaml[standard+].
Phase 4 — Verify (trust-but-verify)
- Run each plugin hook against the target; assert valid JSON on stdout.
- Run
python "${CLAUDE_PLUGIN_ROOT}/scripts/readiness.py" run— a BLOCK on an empty scaffold is the gate working (no content yet), not a failure. Report the score. - Print next steps: customize
README.md+PRD.md, then "Let's frame the problem" (v0.1).
Anti-patterns
| Pattern | Fix |
|---|---|
| Hardcoding the seed file list in the skill | Drive prd-ce-init.sh; it reads template_seed |
| Copying the framework (skills/hooks) into the consumer repo | The plugin provides those live — seed only consumer-owned files |
Overwriting an existing PRD.md/SoT/ | Greenfield-only; the seeder skips what exists |
Leaving PRD.md at the example's version header | Frontmatter reset to v0.1 happens automatically on a fresh seed |
| Treating a readiness BLOCK on a fresh scaffold as a bug | It's the gate working — report the score |
Problem Framing Skill
Transform market signals into evidence-anchored problem statements.
Consumes
This skill assumes you have zero prior research. It is the starting point.
- No prior CFD- entries needed
- No prior PR D required
- Assumes: Founder/PM has observed market signals but hasn't validated them
Produces
This skill creates/updates:
- CFD-* entries (customer feedback) — 1-5 per problem dimension, with confidence scoring (see PRINCIPLES.md)
- PRD.md Why section — Evidence-anchored problem statement table
- MVP scope signal — Identifies which problem dimensions will drive MVP feature scope (handed to v0.3)
All CFD- entries should include:
confidence: 1-3/5(pre-product research, no usage data)- Evidence source (competitive analysis, interviews, workarounds, etc.)
- Forward target: "Would move to 4/5 if we observe 10+ paying customers with this pain"
Workflow Overview
- Assess gaps → Identify what evidence is missing before you can confidently state a problem
- Anchor evidence → Create CFD- entries for each pain point dimension with confidence scoring
- Extract dimensions → Pull multiple distinct problems from each source
- Quantify costs → Add time/money/risk numbers to make pain concrete
- Draft statement → Populate the problem table, tied to CFD- entries
Core Output Template
Populate this table for every problem statement:
| Element | Definition | Evidence |
|---|---|---|
| Who is hurting? | Specific, findable, countable persona | Segment size |
| What pain exists? | Observable behavior or workflow friction | CFD-ID |
| Cost of problem | Time, money, or opportunity lost | Quantified |
| Why now? | Market trigger creating urgency | Trend/event |
| What's impossible? | Opportunity cost—what can't they do | User quote |
See assets/problem-statement.md for copy-paste template.
Step 1: Gap Assessment
Before drafting, create this status table:
| Element | Status | Source |
|---|---|---|
| Who is hurting? | ⚠️ Hypothesis / ✅ Validated / ❌ Missing | |
| What pain exists? | ⚠️ / ✅ / ❌ | |
| Cost of problem | ⚠️ / ✅ / ❌ | |
| Why now? | ⚠️ / ✅ / ❌ | |
| What's impossible? | ⚠️ / ✅ / ❌ |
Gate: Require ≥2 elements ✅ Validated before drafting. If ≥3 elements ❌ Missing, run deep research first. See references/research-prompts.md for research templates.
Step 2: Evidence Anchoring
Create CFD entries for each pain point with confidence scoring:
CFD-###: [Pain Point Name]
Source: [Where this evidence came from]
Tier: [1-5 evidence quality]
Confidence: [1-5]/5 (pre-product research)
Quote: "[Verbatim from source]"
Dimensions: [List distinct problems extracted from this source]
Next Target: "Would move to 3/5 if we interview X more customers"
Evidence Tier Hierarchy (strength of observation):
- Tier 1: Buying behavior (invoices, subscriptions, job budgets) — users spend money to solve this
- Tier 2: Active workarounds (spreadsheets, hired help, manual processes) — users invest labor
- Tier 3: Complaints with cost ("costs me X hours/week") — users quantify the pain
- Tier 4: General complaints ("this is annoying") — users acknowledge it but haven't quantified
- Tier 5: Speculation — REJECT ("users probably want...")
Confidence Scoring (pre-product, see PRINCIPLES.md):
- 1/5: PM assumption or single data point
- 2/5: Secondary research (competitive analysis, market reports)
- 3/5: Pre-product interviews (3-5 user conversations)
- 4/5: Beta cohort validation (observed behavior, not questions)
- 5/5: Production usage (reserved for post-launch)
Example entry with confidence:
CFD-001: Sales teams waste 5+ hours/week on spreadsheet workflow
Source: 3 customer interviews (SaaS sales director, SMB sales rep, enterprise sales manager)
Tier: 2-3 (workaround + cost quantification)
Confidence: 3/5 (source: 3-customer-interviews-jan-2026)
Quote: "I spend 5 hours every Friday reconciling our pipeline with the actual numbers in our CRM"
Dimensions:
- Manual data reconciliation between systems (workaround)
- Inventory work (scheduling impact)
- Single source of truth fragmentation (data quality risk)
Next Target: "Would move to 4/5 if we validate with 5 more sales leaders or observe workflows directly"
Step 3: Pain Dimension Extraction
Extract multiple problems from each source. One quote often contains 3-4 distinct pain dimensions.
Example: "USB sticks removed for every update, no scheduling, screens don't communicate, priced for 100+ displays" → Sneakernet workflow, No dynamic scheduling, No centralization, Price mismatch
Step 4: Cost Quantification
Every problem needs a number:
| Type | Calculation |
|---|---|
| Time | Hours/week × hourly rate |
| Money | Current spend on workaround |
| Opportunity | Revenue/outcomes missed |
| Risk | Penalty × probability |
Step 5: Draft Problem Statement
Use the core output template. Reference CFD-IDs for every claim.
See references/examples.md for good/bad examples with explanations.
Quality Gates
Pass Checklist
- ≥1 Tier 1-2 evidence item
- Cost quantified (time, money, or risk)
- "Who" specific enough to build prospect list
- "Why now" has at least Tier 3 hypothesis
Testability Check
- Can find 10 people with this problem in 48 hours?
- Can observe the pain behavior?
- Can quantify cost without leading questions?
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Vague "Who" | "Small businesses" | → "SMBs with 1-10 screens" |
| Feature-as-problem | "Need a dashboard" | → "Can't see status" |
| Solution creep | "MVP must solve X" | → Stay on problem (v0.4) |
| Missing cost | "This is annoying" | → "Costs X hrs/week" |
| Speculation | "Users might want" | → Find evidence or reject |
Bundled Resources
references/research-prompts.md— Deep research templates by gap type. Use when gap assessment shows ≥3 missing elements.references/examples.md— Good/bad problem statement examples with explanations.assets/problem-statement.md— Copy-paste template for problem tables and CFD entries.
Handoff
Problem statement complete when quality gates pass. Next: v0.2 Market Definition (segments, sizing, ICP).
User Value Articulation Skill
Transform validated pain points into evidence-anchored value statements.
Workflow Position
Problem Framing → User Value Articulation → v0.2 Market Definition
(pain) (value) (who cares most)
Consumes
This skill requires prior work from v0.1:
- **CFD-* entries (pain points, from Problem Framing) — Evidence for what problems users face
- PRD.md Why section (problem statement table) — Context for pain-to-value transformation
This skill assumes v0.1 Problem Framing is complete.
Produces
This skill creates/updates:
- CFD-* entries (tagged as value hypotheses) — Transformation of pain points into value statements, with confidence scoring
- MVP scope signal — Identifies which value dimensions will drive MVP feature scope (handed to v0.3)
All CFD value hypothesis entries should include:
confidence: 2-3/5(based on evidence tier from users or market)- Evidence tier (1-5 per value hierarchy)
- Forward target: "Would move to 4/5 if we validate with beta cohort"
Example value hypothesis entry:
CFD-015: Value Hypothesis — Eliminate manual reconciliation workflow
Source Pain: CFD-001 (sales teams waste 5+ hours/week)
Evidence Tier: 2-3 (workaround + quantified cost)
Confidence: 3/5 (source: 3-customer-interviews-jan-2026)
Value Statement: "Reclaim 5 hours/week for strategic pipeline management"
Transformation: [5 hours wasted] → [5 hours available for growth]
Framing Type: Negative Removal (acute quantified loss)
Quantification: 5 hours/week = ~250 hours/year = $12,500 (at $50/hr)
Next Target: "Would move to 4/5 if we observe beta cohort using this feature"
Workflow Overview
- Receive pain points → Read CFD-IDs from Problem Framing
- Identify value unit → Time / Money / Risk / Capability
- Transform pain → value → Apply transformation pattern
- Anchor to evidence → What proof users want this outcome?
- Create CFD entry → Tag as value hypothesis with tier
Core Output Template
| Element | Definition |
|---|---|
| Pain (source) | CFD-ID from Problem Framing |
| Value Statement | One sentence: what user gains |
| Value Unit | Time / Money / Risk / Capability |
| Quantification | Number with unit |
| Framing Type | Negative Removal / Positive Gain / Capability Unlock / Risk Reduction |
| Evidence Tier | 1-5 per hierarchy |
| Supporting CFD | New CFD-ID for value hypothesis |
See assets/value-statement.md for copy-paste template.
Pain → Value Transformation
| Pain Pattern | Value Pattern |
|---|---|
| "Costs X time" | "Reclaim X time for [higher-value work]" |
| "Costs $X" | "Save $X [or redirect to growth]" |
| "Risks $X penalty" | "Eliminate $X exposure" |
| "Cannot do X" | "Now able to X when [trigger]" |
| "Takes X steps" | "Complete in Y steps" |
| "Manual process" | "Automatic + verifiable" |
Framing Type Selection
| Type | When to Use |
|---|---|
| Negative Removal | Pain is acute, quantified loss; "hate", "wasting", "losing" |
| Positive Gain | Opportunity cost clear; "I wish I could..." |
| Capability Unlock | Something impossible, not just hard; "We can't..." |
| Risk Reduction | Regulatory/compliance; penalty amounts cited |
Value Evidence Tier Hierarchy
| Tier | Description | Weight |
|---|---|---|
| 1 | User already paying for this value elsewhere | ✅ Highest |
| 2 | User actively trying to achieve this outcome | ✅ Strong |
| 3 | User articulates wanting this (unprompted) | ✅ Acceptable |
| 4 | User agrees when prompted | ⚠️ Weak |
| 5 | Builder assumes value | ❌ Reject |
Gate rule: ≥1 value statement must have Tier 1-3 evidence before v0.2.
CFD Entry Format
CFD-###: Value Hypothesis — [Title]
Type: Value Hypothesis
Source Pain: CFD-###
Evidence Tier: [1-5]
Value Statement: "[User gains X measured in Y]"
Transformation: [Pain] → [Value]
Framing Type: [Type]
Quantification: [Number with unit]
See references/transformation-examples.md for worked examples.
Quality Gates
Pass Checklist
- Every pain point has corresponding value statement
- ≥1 value statement has Tier 1-3 evidence
- All values quantified (time, money, risk, capability)
- No feature-as-value statements
- Value unit matches pain unit
Testability Check
- Can explain value in <10 seconds to prospect?
- Can test with landing page headline?
- Value statement contains no features (no "dashboard", "tool")?
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Feature as value | "Dashboard", "tool", "feature" in statement | Rewrite as outcome |
| Unmeasurable | "Better", "improved" without number | Add quantity |
| Disconnected | Pain unit ≠ value unit | Match units |
| Round inflation | "Save 10 hours" no source | Require calculation |
| No evidence | No CFD-ID for user desire | Downgrade tier |
| Solution creep | HOW (feature) not WHAT (outcome) | Remove implementation |
Bundled Resources
references/transformation-examples.md— 3 worked examples from real PRDs with step-by-step transformation process.references/research-prompts.md— Deep research templates when value evidence is Tier 4-5.assets/value-statement.md— Copy-paste template for value tables and CFD entries.
Handoff
Value articulation complete when quality gates pass. Combined with Problem Framing, v0.1 Spark is ready.
Next: v0.2 Market Definition (Who cares MOST about this value? Who pays FIRST?)
Competitive Landscape Mapping
Understand market reality before defining your position.
Workflow Position
v0.1 Spark (Problem + Value) → Competitive Landscape Mapping → Product Type Classification
(what hurts) (who else solves it) (how we compete)
Consumes
This skill requires prior work from v0.1:
- **CFD-* entries (problem statements, from Problem Framing) — Evidence for what users need/want
- **CFD-* entries (value hypotheses, from User Value Articulation) — Desired outcomes users are seeking
- PRD.md Why section — Problem framing and market signals
This skill assumes v0.1 Spark is complete (both problem and value).
Produces
This skill creates/updates:
- CFD-* entries (competitive intelligence) — Analysis of direct competitors, adjacent solutions, workarounds
- BR-* entries (positioning rules) — Constraints derived from landscape analysis
- Landscape map artifact — Current behavior documentation, feature matrix, 1% better hypothesis
All CFD competitive intelligence entries should include:
confidence: 2-3/5(based on evidence tier from public sources + user validation)- Evidence source (G2 reviews, pricing pages, user interviews, etc.)
- Forward target: "Would move to 4/5 if we validate gap with 5+ target users"
Example competitive intelligence entry:
CFD-042: Competitive Intelligence — Competitor Landscape Analysis
Type: Competitive Intelligence
Date: 2026-02-01
Confidence: 3/5 (source: public-research + 3-customer-interviews)
Competitors Analyzed: 4 direct + 2 adjacent
Primary Gap: All competitors require enterprise licensing; SMB segment underserved
Feature Matrix: [Link to matrix]
1% Hypothesis: "SMB sales teams can get 80% of [Competitor A] features for 40% of price"
Evidence:
- CFD-001: 3 SMB teams paying $500/mo but using only 5 of 20 features
- CFD-015: Value hypothesis shows $12,500/year need for core 5 features only
Next Target: "Would move to 4/5 if we validate with 5+ SMB prospects willing to pay $200/mo"
Workflow Overview
- Document current behavior → What users do TODAY (before competitor search)
- Discover alternatives → Direct, adjacent, workarounds, "do nothing"
- Analyze gaps → Industry/geography gaps, underserved segments
- Compare features → Build comparison matrix
- Form hypothesis → 1% better hypothesis with evidence
Core Output Template
| Element | Definition | Evidence |
|---|---|---|
| Current Behavior | How users solve this today | Observed workflow |
| Direct Competitors | Products solving same problem | Revenue/funding proof |
| Adjacent Solutions | Products solving related problems | User overlap |
| Workarounds | DIY solutions (spreadsheets, manual) | Forum/reddit mentions |
| Feature Matrix | Side-by-side capability comparison | Product documentation |
| Gap Analysis | Where competition is weak | Reviews, complaints |
| 1% Hypothesis | How we win | Evidence-anchored |
See assets/landscape.md for copy-paste template.
Step 1: Document Current Behavior
Before searching competitors, document what target users do TODAY.
Capture Format
Current Behavior: [What they do]
Tools Used: [Existing tools, if any]
Time Investment: [Hours/week on workaround]
Pain Points: [From v0.1 CFD-IDs]
Why First?
- Prevents solution bias from competitor features
- Reveals workarounds competitors might miss
- Establishes true baseline for improvement claims
Step 2: Competitor Discovery
Discovery Categories
| Category | Definition | Search Strategy |
|---|---|---|
| Direct | Same problem, same segment | "[problem] software" |
| Adjacent | Related problem, potential pivot | "[related workflow] tool" |
| Workarounds | DIY solutions | Reddit: "how I [task]" |
| Do Nothing | Accept status quo | Why hasn't this been solved? |
Minimum Discovery Checklist
- 3+ direct competitors (or document why fewer exist)
- 2+ adjacent solutions
- 1+ workaround documented
- "Do nothing" cost quantified
Create CFD Entry Per Competitor
CFD-###: Competitor — [Name]
Type: Competitive Intelligence
Source: [Website, G2, Crunchbase]
Date: YYYY-MM-DD
Overview: [1-2 sentences]
Target Segment: [Who they serve]
Pricing: [Model and range]
Revenue/Funding: [If available]
Key Differentiator: [Their claim]
Weakness Signals: [Reviews, complaints]
Step 3: Gap Analysis
Industry/Geography Gap Table
| Industry | Competitors Serving | Gap Level |
|---|---|---|
| [Industry 1] | X of Y | None / Small / Large |
| [Industry 2] | X of Y | None / Small / Large |
Segment Gap Table
| Segment | Served By | Underserved Signal |
|---|---|---|
| Enterprise | [List] | [Signal or "Well served"] |
| Mid-Market | [List] | [Signal or "Well served"] |
| SMB | [List] | [Signal or "Well served"] |
| Prosumer | [List] | [Signal or "Well served"] |
Underserved Signals
- Tier 1: Users paying but complaining (G2 reviews)
- Tier 2: Users building workarounds (Reddit, forums)
- Tier 3: Users asking for solutions (community posts)
- Tier 4: No apparent demand (caution)
Step 4: Feature Comparison Matrix
Build side-by-side comparison:
| Feature | Us (Planned) | Competitor A | Competitor B | Gap |
|---|---|---|---|---|
| [Feature 1] | ✅/❌/🔄 | ✅/❌ | ✅/❌ | [Our advantage] |
| [Feature 2] | ✅/❌/🔄 | ✅/❌ | ✅/❌ | [Our advantage] |
Legend: ✅ = Has | ❌ = Missing | 🔄 = Planned
Matrix Requirements
- Include all "table stakes" features (what everyone has)
- Identify 1-3 differentiating features
- Note pricing tier where features unlock
- Flag features competitors are building (roadmap signals)
Step 5: 1% Better Hypothesis
Template
We can be 1% better than [Competitor X] by [specific improvement] for [specific segment].
Evidence:
- [CFD-ID]: [Supporting evidence]
- [CFD-ID]: [Supporting evidence]
Why This Matters:
- [Segment] cares about this because [reason]
- Current solutions fail at this because [reason]
Risk:
- [What could invalidate this hypothesis]
Hypothesis Quality Check
- "1% better" is specific and measurable
- References CFD-IDs for evidence
- Targets a defined segment
- Explains WHY this gap exists
- Acknowledges risks
Quality Gates
Pass Checklist
- ≥3 competitors documented with CFD-IDs
- Feature matrix with ≥5 compared features
- ≥1 gap identified with Tier 1-2 evidence
- 1% better hypothesis formed
- Current behavior documented FIRST
Testability Check
- Can validate 1% hypothesis in <30 days?
- Can find 10 people in target segment?
- Gap evidence is from users, not assumptions?
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Competitor-first thinking | Started with competitor features | Document current behavior first |
| False uniqueness | "No competitors" claim | Include workarounds and adjacent |
| Feature bloat | Matrix has 20+ features | Focus on differentiators |
| Vague gaps | "Better UX" without evidence | Add specific user complaint |
| 10x claims | "10x better than X" | Start with 1% provable claim |
| Ignored workarounds | Only listed software competitors | Include spreadsheets, manual |
CFD/BR Output Format
CFD Entry (Competitive Intelligence)
CFD-###: Competitive Intelligence — [Market/Segment]
Type: Competitive Intelligence
Date: YYYY-MM-DD
Competitors Analyzed: [Count]
Primary Gap: [Description]
Evidence Tier: [1-5]
Feature Matrix: [Link or inline]
1% Hypothesis: [Statement]
BR Entry (Positioning Rule)
BR-###: Positioning Rule — [Title]
Type: Business Rule
Source: CFD-###
Date: YYYY-MM-DD
Rule: [Specific constraint derived from landscape]
Rationale: [Why this matters]
Applies To: [Scope]
Bundled Resources
references/research-prompts.md— Deep research templates for competitor discovery and gap analysis.references/examples.md— Good/bad competitive analysis examples.assets/landscape.md— Copy-paste template for landscape mapping.assets/feature-matrix.md— Feature comparison matrix template.
Handoff
Competitive landscape complete when quality gates pass. Landscape map informs:
- Product Type Classification (next skill) — What type are we? Clone, Slice, etc.
- v0.3 Pricing — Competitive pricing anchors
- v0.3 Moat — Where competitors are weak
Next: Product Type Classification (How should we compete based on landscape?)
Product Type Classification
Position in HORIZON workflow: v0.2 Competitive Landscape → v0.2 Product Type Classification → v0.3 Outcome Definition
Consumes
This skill requires prior work from v0.2:
- Landscape map artifact (from Competitive Landscape Mapping) — Current behavior documentation, feature matrix, competitor analysis
- CFD-* entries (competitive intelligence, from Competitive Landscape Mapping) — Evidence from 3+ direct competitors + adjacent solutions
- BR-* positioning rules (from Competitive Landscape Mapping) — Constraints derived from competitive analysis
This skill assumes v0.2 Competitive Landscape is complete with documented landscape analysis.
Produces
This skill creates/updates:
- BR-* entries (product type classification) — Decision record showing which of the six types this product is
- BR-* entries (GTM constraints inherited from type) — Pricing, channel, scope, and timeline implications of the chosen type
- Product type artifact — Named decision: "We are building a [Type] product because [specific evidence from landscape]"
Example product type classification entry:
BR-042: Product Type Classification
Type: Classification Decision
Date: 2026-02-01
Confidence: 70% (source: competitive-landscape-analysis + 3-customer-interviews)
Classification: UNDERCUT
Rationale: All 3 direct competitors (Notion, Linear, Figma) serve enterprise/mid-market first; SMB segment underserved. We can deliver 80% of feature set at 40% price for SMB-specific workflows.
Evidence:
- CFD-015 (landscape): "All competitors start at $50/user/month enterprise pricing"
- CFD-018 (landscape): "3 SMB teams using workarounds because pricing doesn't fit budget"
- CFD-001 (value hypothesis): "$12,500/year value for 5 core features only"
GTM Constraints (inherited):
- Pricing: Must be <$200/user/month to justify switching
- Channel: Direct sales to SMB, not marketplace/enterprise
- Scope: Ruthlessly cut features; 5 core + 3 differentiators max
- Timeline: Fast iteration with SMB feedback; can't outspend enterprise marketing
Six Product Types
| Type | Definition | When Evidence Shows |
|---|---|---|
| Clone | Copy proven product, execute better | Leader validated market; weak moat; execution gap |
| Unbundle | Extract one category from horizontal platform | Multi-category platform does your thing poorly |
| Undercut | Same product, simpler + cheaper for niche | Tool overserves broad market; 60%+ price gap possible |
| Slice | Plugin/extension in existing ecosystem | Platform has marketplace; users already there |
| Wrapper | AI/API layer on existing data/tools | Middleware gap between tools; data accessible |
| Innovation | New solution to known problem | Existing approaches fundamentally broken; high pain |
Classification Decision Flow
START: What does v0.2 Competitive Landscape show?
Q1: Is there a dominant horizontal platform doing many things?
YES → Does it do YOUR thing poorly?
YES → UNBUNDLE (extract the vertical)
NO → Continue to Q2
NO → Continue to Q2
Q2: Is there a single-purpose leader with validated market?
YES → Can you price 60%+ lower for a niche?
YES → UNDERCUT
NO → Can you execute better (speed/UX)?
YES → CLONE
NO → Continue to Q3
NO → Continue to Q3
Q3: Does target customer live in a platform ecosystem?
YES → Does platform have marketplace/app store?
YES → SLICE (build extension)
NO → Continue to Q4
NO → Continue to Q4
Q4: Is there a data/API integration gap between tools?
YES → Is the data accessible (API/scraping)?
YES → WRAPPER
NO → Continue to Q5
NO → Continue to Q5
Q5: Are existing solutions fundamentally broken?
YES → Is pain severe enough for education investment?
YES → INNOVATION
NO → Reconsider market
NO → Reconsider market or revisit Q1-Q4
Evidence Requirements Per Type
| Type | Required Evidence (from v0.2 Landscape) | Confidence Threshold |
|---|---|---|
| Clone | Revenue proof + feature gap + weak moat | Medium (50%+) |
| Unbundle | Platform size + category neglect + user complaints | Medium (50%+) |
| Undercut | Price benchmarks + niche pain + simplification path | High (70%+) |
| Slice | Platform MAU + marketplace presence + integration docs | High (70%+) |
| Wrapper | API availability + use case validation + cost model | High (70%+) |
| Innovation | Failed alternatives + severe pain + budget evidence | Very High (85%+) |
Output Template
After classification, create these entries:
BR-XXX: Product Type Classification
Type: [Clone | Unbundle | Undercut | Slice | Wrapper | Innovation]
Confidence: [X]%
Primary Evidence: [CFD-XXX reference]
Classification Rationale: [2-3 sentences]
BR-XXX: GTM Constraints (inherited from type)
Pricing Constraint: [See references/gtm-constraints.md]
Channel Constraint: [See references/gtm-constraints.md]
Scope Constraint: [See references/gtm-constraints.md]
Timeline Implication: [See references/gtm-constraints.md]
Anti-Patterns to Avoid
- Claiming Innovation when it's really Clone: If competitor exists with revenue, you're not innovating
- Undercut without price evidence: Must show 60%+ reduction is possible AND sustainable
- Slice without ecosystem validation: Platform must actually want third-party apps
- Wrapper without API access confirmed: Technical feasibility must precede classification
- Unbundle from small platform: Only works against large horizontal players
Reference Files
- Decision Framework: See
references/decision-framework.mdfor expanded decision trees - Examples: See
references/examples.mdfor good/bad classification cases - GTM Constraints: See
references/gtm-constraints.mdfor type → constraint mapping - Classification Template: See
assets/classification.mdfor structured worksheet
Downstream Impact
Classification constrains v0.3 decisions:
- Outcome metrics must match type (Clone = feature parity; Undercut = price advantage)
- Pricing model anchored to type (Undercut must show savings; Slice follows platform norms)
- MVP scope bounded by type (Clone = match leader; Undercut = ruthlessly cut features)
- GTM channel determined by type (Slice = marketplace; Undercut = direct to niche)
Feature Value Planning
Position in workflow: v0.3 Commercial Model → v0.3 Feature Value Planning → v0.4 User Journeys
Features are the unit of scope. Every feature must trace back to why it exists: outcome, moat, competitive position, or pricing tier.
Consumes
This skill requires prior work from v0.1-v0.3:
- CFD-* entries (customer feedback, from v0.1-v0.2) — Evidence for what users need/want
- KPI-* entries (outcome definitions, from v0.3 Outcome Definition) — What metrics does each feature support
- BR-* moat entries (from v0.3 Moat Definition) — What features defend our competitive position
- BR-* pricing entries (from v0.3 Pricing Model) — What features differentiate tiers
- Market landscape analysis (from v0.2) — Competitive feature comparison
This skill assumes v0.1-v0.2 research is complete and risk/tech decisions (v0.5) are not yet made.
Produces
This skill creates/updates:
- FEA-* entries (feature definitions, with confidence scoring) — Every feature in scope with traceability
- BR-FEA-* entries (governance rules for feature decisions) — Scope protection rules
- MVP-SCOPE artifact — Explicit list: "These X features (FEA-001, FEA-005, FEA-008) define our MVP"
- Example:
MVP-SCOPE: 5 P0 features + 3 P1 features = 8 total. Rationale: Delivers value on [KPI-001, KPI-002]. Competitive parity [FEA-001-003], Delta [FEA-004], Pricing [FEA-005] - This becomes the definition for v0.4 user journeys and v0.7 build scope
- Example:
All FEA- entries include confidence:
confidence: 2-3/5(based on CFD- evidence strength)- Evidence: "CFD-001, CFD-005, competitive-analysis"
- Forward target: "Would move to 4/5 if beta cohort uses it"
Feature Classification Framework
| Type | Definition | Strategic Purpose | Evidence Required |
|---|---|---|---|
| Moat | Builds/defends competitive advantage | Supports BR- moat rule | High (CFD- proving differentiation) |
| Outcome | Directly drives success metric | Tied to KPI- entry | High (KPI- link mandatory) |
| Parity | Matches competitor baseline | From Competitive Landscape | Medium (CFD- competitor evidence) |
| Delta | Differentiation from competitors | Our advantage over market | High (CFD- gap evidence) |
| Tier | Differentiates pricing packages | From Pricing BR- | Medium (BR- tier assignment) |
| Table Stakes | Expected but not differentiating | Industry standard | Low (common knowledge) |
Rule: P0 features require Moat, Outcome, or Delta classification. Table Stakes alone cannot justify P0.
Product Type × Feature Strategy
Feature focus varies by product type (from v0.2 classification):
| Product Type | Primary Focus | Parity Approach | Delta Approach |
|---|---|---|---|
| Fast Follow | Parity + focused delta | 1:1 critical feature match | Single compelling improvement |
| Innovation | Moat-building features | Minimal (new category) | Core differentiation IS the product |
| Slice | Segment-specific features | Partial (niche needs differ) | Deep fit for underserved segment |
Fast Follow Constraint
BR-FEA-PARITY-FIRST: No delta features until parity features complete. Users compare to incumbent first.
Innovation Pattern
Moat features = 60%+ of scope. Table stakes minimized. Delta is the entire value proposition.
Slice Pattern
80/20 rule: Match 20% of incumbent features that serve 80% of niche use cases. Delta = niche-specific depth.
Priority Tier Criteria
| Tier | Criteria | Evidence Threshold |
|---|---|---|
| P0 — Must Have | Blocks launch without it; tied to primary KPI- or moat BR- | CFD- proof + KPI-/BR- link |
| P1 — Should Have | Meaningfully improves outcome; supports tier differentiation | CFD- user signal |
| P2 — Nice to Have | Enhances experience; no direct KPI impact | Reasonable assumption OK |
| P3 — Defer/Cut | Scope creep signal; can add post-launch | None (remove from scope) |
Kill criterion: If >40% of features are P2/P3, scope is bloated. Re-evaluate.
FEA- Output Template
Create FEA- entries in this format:
FEA-XXX: [Feature Name]
Type: [Moat | Outcome | Parity | Delta | Tier | Table Stakes]
Priority: [P0 | P1 | P2 | P3]
Description: [What the feature does — user-facing capability]
Outcome Link: [KPI-XXX this supports, or "N/A"]
Moat Link: [BR-XXX moat rule this supports, or "N/A"]
Pricing Link: [BR-XXX tier this belongs to, or "All tiers"]
Competitor Comparison: [Parity with X | Delta vs X | Unique | Table stakes]
Validation: [CFD-XXX evidence, or validation method]
Acceptance Criteria: [Testable condition for "done"]
Example entries:
FEA-001: One-Click Scheduling
Type: Parity
Priority: P0
Description: Schedule meetings with single click from availability view
Outcome Link: KPI-002 (activation rate)
Moat Link: N/A
Pricing Link: All tiers
Competitor Comparison: Parity with Calendly
Validation: CFD-012 (competitor feature audit)
Acceptance Criteria: User completes scheduling in ≤3 clicks
FEA-002: Offline Mode
Type: Delta
Priority: P0
Description: Full functionality without internet connection
Outcome Link: KPI-001 (TTFV for field users)
Moat Link: BR-012 (moat: works anywhere)
Pricing Link: BR-045 (Pro tier differentiator)
Competitor Comparison: Delta vs Notion (requires connection)
Validation: CFD-018 (user interviews: connectivity complaints)
Acceptance Criteria: All core features function with 0 connectivity for 24h
BR-FEA- Governance Rules
Create governance rules for feature decisions:
BR-FEA-XXX: [Rule Name]
Type: [Scope Protection | Prioritization Rule | Validation Gate]
Rule: [Constraint statement]
Rationale: [Why this rule exists]
Enforcement: [When/how applied]
Standard rules to establish:
BR-FEA-001: Outcome Link Required— P0/P1 features must link to KPI- entryBR-FEA-002: Validation Before Build— P0 features require CFD- evidence before developmentBR-FEA-003: Scope Freeze Gate— Feature list locked after v0.4; changes require EPIC
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Feature creep | P2/P3 > 40% of scope | Cut ruthlessly; defer to backlog |
| Implementation masquerading as feature | "Use Redis caching" | Reframe as user outcome |
| Orphaned features | No KPI-, BR-, or CFD- link | Add traceability or cut |
| Assumption-based priority | "Users will love this" | Require CFD- evidence |
| Parity inflation | Everything is "parity" | Challenge: is competitor feature actually used? |
| Delta without moat | Delta feature easy to copy | Tie to defensible BR- moat |
Downstream Connections
This skill's outputs feed into multiple downstream skills:
| Consumer | Consumes | Purpose |
|---|---|---|
| v0.4 User Journeys | FEA-* entries + MVP-SCOPE artifact | Design journey paths through MVP features |
| v0.5 Red Team Review | FEA-* entries | Assess technical/risk feasibility of features |
| v0.6 Architecture | FEA-* entries + MVP-SCOPE | Design system that supports MVP features |
| v0.7 Build Execution | FEA-* entries + MVP-SCOPE | Define EPIC scope (which features = which EPICs) |
| v0.9 GTM | FEA-* entries (especially Delta) | Build launch messaging around delta features |
Critical handoff: The MVP-SCOPE artifact is the boundary. Everything in the list goes to v0.4+. Everything outside gets deferred to post-launch backlog.
Detailed References
- Good/bad examples: See
references/examples.md - FEA- entry template: See
assets/fea.md - Competitive feature matrix: See
assets/competitive-feature-matrix.md
Moat Definition
Position in HORIZON workflow: v0.2 Competitive Landscape → v0.3 Moat Definition → v0.3 Pricing Model Selection
Consumes
This skill requires prior work from v0.2:
- Landscape map artifact (from Competitive Landscape Mapping) — Current behavior documentation, feature matrix, competitor analysis
- CFD-* entries (competitive intelligence, from Competitive Landscape Mapping) — Documented competitors with pricing, features, user feedback
- BR-* product type entry (from Product Type Classification) — Classification constrains which competitors are relevant to analyze
This skill assumes v0.2 analysis is complete with documented competitors.
Produces
This skill creates/updates:
- CFD-* entries (competitor moat analysis) — Assessment of each competitor's defensibility by moat type
- BR-* entries (targeting rules) — Constraints derived from moat analysis, defining where to compete vs. avoid
- Moat strength inventory artifact — Summary of competitor moats with vulnerability signals
All CFD moat analysis entries should include:
confidence: 2-3/5(based on public evidence + user interviews about switching friction)- Evidence source (pricing pages, reviews, customer interviews)
- Forward target: "Would move to 4/5 if we interview 5+ current/former customers about switching costs"
Example moat analysis entry:
CFD-055: Competitor Moat Analysis — Notion
Competitor: Notion
Primary Moat Type: Switching Costs (data lock-in)
Moat Strength Tier: Strong
Confidence: 3/5 (source: public-research + 2-user-interviews)
Date: 2026-02-01
Switching Cost Quantification:
- Financial: Multi-year contract, no early termination ($0 direct cost)
- Time/Effort: 20+ hours migration, team retraining
- Data Migration: Proprietary database format (complex export)
- Workflow Retraining: Unique templates, team habits
- Integration Rework: Deep Slack/GitHub dependencies
Total Switching Cost: $3K in labor + 20 hours = Material friction
Moat Verdict: Strong — switching costs >$3K + meaningful time investment
Vulnerability Signal: SMB segment with small teams; they use <20% of feature set (opportunity for simpler tool)
Targeting Decision: Avoid direct competition. Wedge in SMB with simplified, cheaper offering.
Evidence:
- CFD-042 (landscape): Reviews show enterprise love; SMB complaints focus on cost + complexity
- CFD-015 (value hypothesis): SMB would save $12,500/year with simpler tool
Next Target: "Would move to 4/5 if we interview 5+ SMB teams about exact switching cost dollars"
Moat Type Taxonomy
Every moat falls into one of six types. Identify primary + secondary moats per competitor:
| Moat Type | Definition | Strong When | Weak When |
|---|---|---|---|
| Switching Costs | Friction to leave (data, workflow, contracts) | Multi-year data, deep integrations | Easy export, monthly contracts |
| Network Effects | Value increases with users | Two-sided marketplace, content platform | Single-player tool, linear value |
| Data/IP | Proprietary data or algorithms | Unique training data, patents | Commodity ML, public datasets |
| Brand/Trust | Recognition, credibility | Regulated industry, high-risk decisions | Low-stakes, undifferentiated |
| Scale/Cost | Volume economics | Infrastructure-heavy, marginal cost near zero | Labor-intensive, linear cost |
| Regulatory | Compliance barriers | Certifications required, government contracts | No compliance requirements |
For micro-SaaS: Switching costs and brand/trust matter most. Network effects and scale rarely apply.
Moat Strength Tiers
Rate each competitor's defensibility:
| Tier | Criteria | Evidence Signals | Targeting Implication |
|---|---|---|---|
| Impenetrable | Multi-layered moat, 10+ years data lock-in | "Would take years to switch" | Avoid direct competition |
| Strong | Significant switching friction, 1-2 year contracts | High NPS + low churn despite complaints | Target underserved segments only |
| Moderate | Some friction, workarounds exist | Churn 5-10%, export options | Wedge opportunity exists |
| Weak | Easy to replace, commodity offering | Monthly plans, high churn, price shopping | Direct competition viable |
| Eroding | Former strength declining | New alternatives gaining share | Aggressive targeting |
Gate rule: Don't compete where incumbent has Impenetrable or Strong moat unless targeting segment they explicitly ignore.
Switching Cost Inventory
Quantify ALL switching costs — the sum determines moat strength:
| Cost Type | High Impact | Low Impact | How to Assess |
|---|---|---|---|
| Financial | >6mo contract, early termination fees | Monthly billing, no penalty | Check pricing page terms |
| Time/Effort | 40+ hr migration, retraining | <4 hr setup, familiar UX | Trial the competitor |
| Data Migration | Proprietary format, no export | Standard export (CSV, API) | Test export function |
| Workflow Retraining | Unique methodology, team habits | Standard patterns | Read onboarding docs |
| Integration Rework | Deep API dependencies | Standalone tool | Map their integrations |
Calculation: Sum hours + dollars. >$5K or >40hr = material switching cost.
Targeting Decision Framework
Use moat analysis to determine where to compete:
Moat Impenetrable/Strong → DON'T COMPETE HERE
↓ unless
Target ignored segment (SMB, specific vertical)
Moat Moderate → WEDGE STRATEGY
↓ identify
Entry point that bypasses switching friction
Moat Weak/Eroding → DIRECT COMPETITION
↓ execute
Feature + price attack on their core
Wedge Opportunity Signals
A wedge exists when:
- Competitor moat doesn't apply to specific segment
- One feature has LOW switching cost (can start there)
- Integration allows coexistence (not replacement)
- Price sensitivity > switching friction
Analysis Workflow
Step 1: Pull Competitor Data
Retrieve CFD- entries from v0.2 Competitive Landscape. For each competitor, you need: pricing, complaints, feature set.
Step 2: Identify Moat Type
For each competitor, determine primary moat type. Use evidence from reviews, pricing structure, integration depth.
Step 3: Rate Moat Strength
Apply tier criteria. Flag if insufficient evidence (Tier 4-5 confidence).
Step 4: Inventory Switching Costs
Complete the 5-category switching cost assessment. Quantify hours + dollars.
Step 5: Identify Vulnerabilities
Where is their moat weakest? Which segments do they ignore? What's eroding?
Step 6: Generate IDs
CFD entries (customer_feedback.md): Template: assets/cfd-moat-analysis.md
CFD-MOT-###: [Competitor] Moat Analysis — [Moat Type], [Strength Tier]
BR entries (BUSINESS_RULES.md): Template: assets/br-targeting.md
BR-TGT-###: [Targeting Rule] — based on [Competitor] moat weakness
Anti-Patterns to Avoid
| Don't | Do Instead |
|---|---|
| "They're big" | Specify which moat type + evidence |
| Assume low switching cost | Quantify: hours + dollars |
| Only analyze direct competitors | Include Type 4-5 (workarounds, inertia) |
| Underestimate integration moat | Map actual dependency depth |
| Ignore eroding moats | Track signals: new entrants, complaints |
| Target where moat is strong | Find the segment where moat doesn't apply |
Output Requirements
Before advancing to Our Moat Articulation:
- ≥3 competitors with moat type identified
- ≥2 competitors with switching costs quantified
- Moat strength tier assigned (with evidence)
- Targeting decision per competitor (compete/avoid/wedge)
- CFD-MOT entries created (≥3)
- BR-TGT entries created (≥2)
Downstream Connections
| Consumer | What It Needs | Format |
|---|---|---|
| v0.3 Our Moat Articulation | Where competitors are weak, what moats work | CFD-MOT entries |
| v0.3 Pricing Model | What price points bypass switching friction | BR-TGT entries |
| v0.5 Red Team | Risks of competitor response | Moat strength tiers |
| v0.9 GTM | Positioning against competitor moats | Targeting rules |
Detailed References
- Good/bad examples: See
references/examples.md - CFD-MOT template: See
assets/cfd-moat-analysis.md - BR-TGT template: See
assets/br-targeting.md
Outcome Definition
Position in HORIZON workflow: v0.2 Product Type Classification → v0.3 Outcome Definition → v0.3 Pricing Model Selection
Consumes
This skill requires prior work from v0.2:
- BR-* product type entry (from Product Type Classification) — Classification determines which metrics are relevant
- CFD-* entries (from Problem Framing and Competitive Landscape) — Customer evidence about desired outcomes
- Market benchmarks and competitor metrics — Reference data for Tier 1/2 targets
This skill assumes v0.2 classification is complete.
Produces
This skill creates/updates:
- KPI-* entries (outcome definitions) — Measurable success metrics tied to product type
- BR-* outcome rules (optional) — Constraints derived from KPI thresholds (e.g., "Launch blocked if LTV:CAC < 3:1")
- Success criteria artifact — Dashboard of leading + lagging indicators that define product-market fit
All KPI entries should include:
confidence: 2-3/5(based on benchmark evidence, not just assumptions)- Evidence source (competitor benchmarks, CFD validation, industry reports)
- Forward target: "Would move to 4/5 if we observe real customer data"
Example KPI entry with confidence:
KPI-001: Time to First Revenue
Type: Tier 1 (Revenue)
Category: Lagging
Definition: Days from market signal identification to first paying customer
Target: ≤14 days
Confidence: 2/5 (source: GearHeart-methodology + 0-customer-validation)
Evidence: BR-001 (GearHeart standard); No pre-customer validation yet
Next Target: "Would move to 4/5 if actual customer reaches paying status in ≤14 days"
Downstream Gate: v0.5 Red Team — if not hit by Day 21, evaluate pivot
---
KPI-002: Conversion Rate (Trial → Paid)
Type: Tier 2 (Leading Indicator)
Category: Leading
Definition: (Paid customers / Trial signups) × 100, measured over 60-day trial period
Target: ≥15% (benchmark: SaaS median 10-15%)
Confidence: 3/5 (source: SaaS-benchmarks + 1-SMB-validation-conversation)
Evidence: CFD-042 (competitive landscape shows SMB conversion patterns)
Next Target: "Would move to 4/5 if we see actual cohort conversion in our product"
Downstream Gate: v0.7 Build Execution — EPIC complete when KPI-002 validated
Metric Quality Hierarchy
Not all metrics are equal. Use this tier system:
| Tier | Metric Types | Why It Matters |
|---|---|---|
| Tier 1 | Revenue (MRR, first dollar, ACV), Churn (logo, NRR), LTV:CAC | Revenue validates market fit. "First dollar IS the proof." |
| Tier 2 | Conversion rates (trial→paid, lead→customer), Time to Value, Activation | Leading indicators that predict Tier 1 outcomes |
| Tier 3 | Engagement (DAU, sessions), Feature adoption, NPS | "Nice to know" — only track if tied to Tier 1/2 |
Rule: Every product needs at least one Tier 1 metric. Tier 3 metrics without Tier 1/2 correlation are vanity metrics.
Product Type × Metric Selection
Metrics must align with product type from v0.2 classification:
| Product Type | Primary Metrics | Anti-Metrics (Avoid) |
|---|---|---|
| Clone | Feature parity score, Price delta vs. leader, TTFV vs. leader | Generic engagement (doesn't prove you beat leader) |
| Undercut | Price per [unit] vs. leader, Niche conversion rate, CAC in target segment | Broad market share (you're niche by design) |
| Unbundle | Category NPS vs. platform, Vertical retention, Feature depth usage | Platform-level metrics (irrelevant to your slice) |
| Slice | Marketplace ranking, Install→activate rate, Platform retention lift | TAM metrics (platform owns the market) |
| Wrapper | Time saved per workflow, API reliability, Integration adoption | Standalone usage (value is in connection) |
| Innovation | Education→activation conversion, Behavioral change rate, Reference customers | User counts without activation (people try, don't convert) |
Leading vs. Lagging Framework
Every product needs BOTH:
Leading Indicators (actionable now, predict outcomes):
- Sequences sent, open rates, trial starts
- Time to first value, activation rate
- Feature adoption in first 7 days
Lagging Indicators (confirm strategy worked):
- MRR, churn rate, LTV:CAC
- Net Revenue Retention (NRR)
- Customer count, logo churn
Pattern: Track leading weekly, lagging monthly. If leading indicators fail, you can pivot before lagging indicators confirm disaster.
Target-Setting Rules
Targets must be evidence-based, never arbitrary:
Good targets (use these approaches):
- Competitor benchmark × safety margin: "SMB churn benchmark 3-5% → use 5%"
- Revenue gates: "First dollar by Day 14" (Signal → $1: 14 days)
- Ratio thresholds: "LTV:CAC ≥ 3:1"
- Time bounds: "TTFV < 5 minutes for self-serve"
Bad targets (anti-patterns):
- Round numbers without evidence: "10% improvement"
- Engagement without revenue tie: "1000 DAU"
- Aspirational without baseline: "Best in class retention"
Output Template
Create KPI- entries in this format:
KPI-XXX: [Metric Name]
Type: [Tier 1 | Tier 2 | Tier 3]
Category: [Leading | Lagging]
Definition: [Exact calculation formula]
Target: [Specific threshold with evidence source]
Evidence: [CFD-XXX or benchmark source]
Downstream Gate: [Which decision uses this — e.g., "v0.5 Red Team kill criteria"]
Measurement: [How/when measured — e.g., "Weekly via Mixpanel"]
Example KPI- entry:
KPI-001: Time to First Revenue
Type: Tier 1
Category: Lagging
Definition: Days from market signal identification to first paying customer
Target: ≤14 days (GearHeart standard: Signal → $1: 14 days)
Evidence: BR-001 (GearHeart methodology)
Downstream Gate: v0.5 Red Team — if not hit by Day 21, evaluate pivot
Measurement: Manual tracking in PRD changelog
Anti-Patterns to Avoid
- Vanity metrics as primary: "50K users" means nothing if only 500 pay
- Traffic without quality: High volume + low engagement = quality problem
- Arbitrary targets: "10% improvement" without baseline or benchmark
- All lagging, no leading: Can't course-correct if you only see outcomes monthly
- Ignoring product type: Clone metrics ≠ Innovation metrics
- Unmeasurable outcomes: "Better experience" — how do you know?
Downstream Connections
KPI- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.5 Red Team | Kill thresholds | "If KPI-001 not hit by Day 21, pivot" |
| v0.7 Build Execution | EPIC acceptance criteria | "EPIC complete when KPI-002 validated" |
| v0.9 GTM | Launch dashboard | Track KPI-001, KPI-003 post-launch |
| BR- Business Rules | Derived constraints | "BR-XXX: No launch if LTV:CAC <3:1" |
Detailed References
- Good/bad examples: See
references/examples.md - Benchmark sources: See
references/benchmarks.md - KPI template worksheet: See
assets/kpi.md
Pricing Model Selection
Position in HORIZON workflow: v0.2 Product Type Classification → v0.3 Pricing Model Selection → v0.3 Moat Articulation
Consumes
This skill requires prior work from v0.2-v0.3:
- BR-* product type entry (from Product Type Classification) — Determines which pricing model makes sense
- CFD-* competitive intelligence entries (from Competitive Landscape Mapping) — Competitor pricing, WTP signals
- BR-* moat entries (from Moat Definition, parallel v0.3 work) — Price as potential moat element
- KPI-* outcome entries (from Outcome Definition, parallel v0.3 work) — Success metrics tied to pricing
- Cost structure estimates (from own analysis) — Unit economics to validate price floors
This skill assumes v0.2 competitive analysis is complete and product type is defined.
Produces
This skill creates/updates:
- BR-PRC-* entries (pricing constraints) — Rules governing price floors, ceilings, discounts
- BR-PKG-* entries (packaging rules) — Tier boundaries and feature gates
- BR-CMP-* entries (competitive positioning) — Price anchor targets and undercut thresholds
- Pricing model artifact — Named decision: "We will use [Model] because [evidence]" with tier definitions
All BR pricing entries should include:
confidence: 2-3/5(based on WTP evidence tier and competitor benchmarks, not assumptions)- Evidence source (competitor pricing, customer interviews, cost structure)
- Forward target: "Would move to 4/5 if real customers validate WTP"
Example pricing rule entry:
BR-PRC-001: Entry Price Floor
Rule: Entry tier never below $15/mo (annual) or $19/mo (monthly)
Confidence: 2/5 (source: CAC-estimate + competitor-benchmarks)
Rationale: Below $15/mo, CAC payback exceeds 6 months, unsustainable
Enforcement: Stripe product configuration, pricing page, contract templates
Evidence:
- CFD-042 (competitor pricing): Similar tools start at $15-25/mo
- KPI-001 (outcome): CAC estimate $45, need 3-month payback = $15/mo minimum
Enforcement: Set in Stripe, document in pricing page, enforce in sales contracts
Exception: Founding customer 50% discount (must be approved by founder)
Next Target: "Would move to 4/5 if 5+ paying customers validate willingness at $15/mo"
---
BR-CMP-002: Competitive Undercut Threshold
Rule: Maintain ≥50% savings vs [Competitor Name] at SMB level (5 users)
Confidence: 3/5 (source: competitor-pricing + 2-SMB-interviews)
Rationale: Price advantage is core differentiator for SMB segment (per product type: UNDERCUT)
Enforcement: Quarterly competitive price audit; triggers price review if competitor drops
Evidence:
- BR-001 (product type: Undercut)
- CFD-015 (value hypothesis): SMB would save $12,500/year at target price
- CFD-042 (competitor pricing): Competitor at $30/user/mo = $1,800/year for SMB
Exception: If competitor drops price, floor (BR-PRC-001) takes precedence
Next Target: "Would move to 4/5 if SMB cohort pays premium for our service over incumbent"
Core Principle
Pricing follows value timing: When and how customers receive value determines the pricing model. Don't copy competitors without understanding their value delivery pattern.
Pricing Model × Product Type Matrix
| Product Type | Typical Model | Why It Fits | Anti-Model (Avoid) |
|---|---|---|---|
| Fast Follow | Match market structure | Users expect familiar pricing | Premium positioning (no differentiation) |
| Undercut | Flat rate, aggressive discount | Price IS the value prop | Per-user (negates savings) |
| Clone | Parity or slight discount | Must compete on terms users know | Innovation pricing (confuses buyers) |
| Slice | Usage-based or ecosystem-tied | Value tied to platform activity | Flat fee (misaligned with usage) |
| Wrapper | Per-integration or usage | Value = connections made | Per-seat (value isn't user count) |
| Innovation | Value-based, potentially premium | Funds education, signals quality | Race to bottom (devalues category) |
Value Timing → Model Selection
Ask: When does the customer get value?
| Value Pattern | Recommended Model | Examples |
|---|---|---|
| Continuous recurring | Subscription (monthly/annual) | SaaS tools used daily |
| Per-transaction | Usage-based | API calls, exports, generations |
| One-time outcome | One-time fee or lifetime | Logo design, course completion |
| Milestone-based | Tiered + upsell triggers | Features unlock as needs grow |
Competitive Anchoring Decision Tree
1. Do competitors use per-user pricing?
├─ YES → Calculate "SMB penalty" (5-user annual cost)
│ └─ Flat pricing at 50%+ savings = strong positioning
└─ NO → Match model, differentiate on value/features
2. Is competitor pricing transparent?
├─ YES (Tier 1) → Use as direct anchor
└─ NO ("Contact sales") → Find proxy or G2/Capterra estimates
3. Should we undercut, match, or go premium?
├─ Undercut: When we're simpler/niche and can sustain margins
├─ Match: When competing on features, not price
└─ Premium: Only with clear, provable differentiation
SMB Penalty Calculation
Per-user pricing penalizes SMBs with larger teams. Calculate the arbitrage:
Competitor: $30/user/mo
SMB with 5 users: $30 × 5 × 12 = $1,800/year
Our flat rate: $99/year
Savings: ($1,800 - $99) / $1,800 = 94%
Headline: "94% less than [Competitor] for teams of 5"
Rule: If savings exceed 70%, lead with price in positioning.
WTP Validation Hierarchy
| Tier | Method | Confidence | When to Use |
|---|---|---|---|
| 1 (Highest) | Actual purchase, payment collected | 95%+ | Post-MVP, real customers |
| 2 | Pre-order, payment intent, trial→paid | 70-85% | Landing page tests |
| 3 | Email signup at stated price | 50-65% | Smoke tests |
| 4 | Survey, interview ("would you pay X?") | 25-40% | Early exploration only |
| 5 (Lowest) | Assumption, gut feel | <20% | Never use alone |
Gate rule: Tier 1-2 evidence required before locking pricing. Tier 4-5 only for hypothesis generation.
Free Tier Design Rules
Only include a free tier if it serves a strategic purpose:
| Purpose | Free Tier Design | Example |
|---|---|---|
| Viral acquisition | Generous + sharing incentive | Dropbox referral |
| Product-led growth | Useful enough to hook, limited enough to upgrade | Notion personal |
| Market education | Demo the category value | New category tools |
| Usage seeding | Get data/content, charge for output | Canva designs |
Anti-patterns:
- Free tier that satisfies most users (no upgrade trigger)
- Free tier that requires support (costs without revenue)
- "Free forever" for unlimited users (cannibalizes paid)
Rule: Every free tier needs a clear upgrade trigger tied to value moment.
Tier Design Framework
Structure tiers around value events, not feature count:
| Tier | Purpose | Design Principle |
|---|---|---|
| Free/Trial | Hook and demonstrate value | First win in <5 minutes |
| Entry/Starter | Convert to paying | Lowest price that sustains business |
| Pro/Growth | Capture value from power users | Features that scale with success |
| Enterprise | Custom needs, high touch | SLAs, SSO, dedicated support |
Tier boundary rules:
- Entry price = CAC payback in ≤3 months
- Pro upgrade trigger = clear usage milestone (not feature gate)
- Enterprise = only if you can support it (don't fake it)
BR- Output Format
Create pricing BR- entries using this structure:
BR-PRC-XXX: [Rule Name]
Rule: [Imperative statement — what MUST happen]
Rationale: [Business driver — why this rule exists]
Enforcement: [Where enforced — code, contract, process]
Evidence: [WTP validation, competitor anchor, cost structure]
Exception: [Override conditions and approver]
BR- Categories
| Prefix | Category | Example Rules |
|---|---|---|
BR-PRC- | Price constraints | Price floor, ceiling, discount cap |
BR-PKG- | Packaging rules | Tier boundaries, feature gates |
BR-CMP- | Competitive positioning | Anchor target, undercut threshold |
Example BR- Entries
BR-PRC-001: Entry Price Floor
Rule: Entry tier never below $15/mo (annual) or $19/mo (monthly)
Rationale: Below $15/mo, CAC payback exceeds 6 months
Enforcement: Stripe product configuration, pricing page
Evidence: CAC estimate $45, need 3-month payback
Exception: Founding customer 50% discount (Matt approval)
BR-PKG-002: Free Tier Upgrade Trigger
Rule: Free tier limited to 50 [units]; show upgrade at 40 (80%)
Rationale: Create natural upgrade moment without frustration
Enforcement: Usage tracking + UI prompt at threshold
Evidence: CFD-XXX shows competitors gate at 25-100 units
Exception: None — critical for conversion funnel
BR-CMP-003: Competitive Price Anchor
Rule: Maintain ≥50% savings vs [Competitor] at 5-user level
Rationale: Price advantage is core differentiator for SMB segment
Enforcement: Quarterly competitive price review
Evidence: CFD-XXX (competitor pricing); BR-001 (product type: Undercut)
Exception: If competitor drops price, floor takes precedence
Anti-Patterns to Avoid
| Don't | Do Instead |
|---|---|
| Copy competitor pricing blindly | Understand their value timing and cost structure |
| Innovation product at Fast Follow price | Price for value, not market incumbents |
| Free tier without upgrade trigger | Define clear conversion moment |
| Discount to win deals | Maintain price integrity, add value |
| Change pricing weekly | Set, validate, iterate quarterly |
| Gut-feel price points | WTP validation (Tier 1-2 evidence) |
Validation Workflow
Before locking pricing:
- Calculate cost floor: What's minimum price for positive unit economics?
- Identify anchor: What do customers pay today? (competitor or workaround)
- Design tiers: Entry + Pro minimum; free only if strategic
- Test WTP: Landing page with price, measure signup conversion
- Lock BR- entries: Document as enforceable rules
Output Requirements
Before advancing to Moat Articulation:
- Pricing model selected with rationale (ties to product type)
- Price anchor identified (CFD- reference)
- Entry price point defined with unit economics check
- Tier boundaries defined (or "no tiers" justified)
- Free tier decision documented (yes + trigger, or no + why)
- WTP validation plan created (even if not yet executed)
- ≥3 BR-PRC/PKG/CMP entries created
Downstream Connections
| Consumer | What It Uses | Example |
|---|---|---|
| v0.3 Moat Articulation | Price as moat element | "Price leadership" defense |
| v0.5 Red Team | Pricing risk assessment | "What if competitor undercuts?" |
| v0.9 Unit Economics | Price inputs to CAC/LTV | Revenue per customer calculation |
| GTM Strategy | Pricing messaging | "91% less than [Competitor]" |
Detailed References
- Good/bad examples: See
references/examples.md - BR- template worksheet: See
assets/br-pricing.md
Persona Definition
Position in workflow: v0.3 Feature Value Planning → v0.4 Persona Definition → v0.4 User Journey Mapping
Personas are not demographic profiles—they are behavioral models synthesized from evidence. Every persona must trace back to CFD- research, BR- targeting rules, and FEA- features they care about.
Consumes
This skill requires prior work from v0.1-v0.3:
- CFD-* problem statements and pain points (from v0.1 Problem Framing) — Behavioral signals about what users struggle with
- CFD-* value hypotheses (from v0.1 User Value Articulation) — Evidence about what users want to accomplish
- CFD-* competitive intelligence and segment gaps (from v0.2 Competitive Landscape) — Market segmentation and underserved signals
- BR-* targeting rules (from v0.3 Moat Definition) — Constraints on which segments to pursue (switchers vs. new-to-category, etc.)
- BR-* product type classification (from v0.2 Product Type Classification) — Determines which personas matter (Clone = feature parity users; Undercut = price-sensitive niche)
- FEA-* entries (from v0.3 Features Value Planning) — Feature list to validate which features each persona cares about
- MVP-SCOPE artifact (from v0.3 Features Value Planning) — The explicit list of features defining MVP; personas map to MVP feature set only
This skill assumes v0.1-v0.3 work is complete.
Produces
This skill creates/updates:
- PER-* entries (persona definitions, confidence 2-3/5) — Behavioral profiles tied to CFD/BR/FEA evidence with acquisition channels and pricing sensitivity
- Persona coverage artifact — Map of which personas are Primary/Secondary and which product type segments they represent
All PER- entries should include:
confidence: 2-3/5(based on evidence tier from CFD interviews and BR targeting decisions)- Evidence source citations (CFD-ID references + BR-ID targeting rules)
- Forward target: "Would move to 4/5 if we validate persona behaviors with 5+ actual customers"
Example PER- entry with confidence:
PER-001: The Overwhelmed Ops Manager
Source IDs: CFD-003 (pain: manual tracking), CFD-012 (value: automation), BR-041 (targeting: switchers at renewal)
Type: Primary
Confidence: 3/5 (source: 4-customer-interviews-jan-2026 + competitive-landscape confirms segment underserved)
Segment: SMB SaaS companies (10-50 employees)
Demographics:
Role: Operations Manager / Head of Ops
Context: Growing startup, wearing multiple hats, no dedicated tools budget
Technical Level: Intermediate (comfortable with SaaS, not a developer)
Behavioral Profile:
Goals: Reduce time spent on manual reporting (CFD-012)
Frustrations: Current tools require too much setup (CFD-003)
Decision Factors: Ease of use > feature count, must show ROI to CEO (CFD-025)
Current Workflow: Spreadsheets + manual data entry + weekly report compilation
Product Relationship:
Primary Value: CFD-012 ("Save 5 hours/week on reporting")
Key Features: FEA-001 (auto-sync), FEA-003 (one-click reports), FEA-007 (dashboard) — all in MVP-SCOPE
Pricing Sensitivity: BR-030 (SMB tier ≤$50/mo)
Acquisition Channel: BR-041 (target at contract renewal of competing tools)
Marketing Hook: "Stop building reports. Start using them."
Next Target: "Would move to 4/5 if 5+ actual SMB ops managers validate this behavior in paid usage"
Core Constraint
Maximum 5 personas. Most products need 1-2.
If you have more than 3, you're likely over-segmenting by demographics instead of behavior. Consolidate ruthlessly.
Persona Types
| Type | Definition | When to Create |
|---|---|---|
| Primary | Core user, drives most revenue | Always (at least 1) |
| Secondary | Important but not primary buyer | If distinct needs exist |
| Negative | Who we explicitly exclude | If exclusion is strategic |
| Aspirational | Future target, not current focus | Only for roadmap planning |
Rule: Primary personas must link to primary revenue KPI-. If a persona doesn't influence revenue, question whether it's truly primary.
Evidence Requirements
Every persona field must link to prior stage evidence:
| Persona Field | Must Link To | Source Stage |
|---|---|---|
| Goals | CFD- value hypothesis | v0.1 User Value Articulation |
| Frustrations | CFD- pain points | v0.1 Problem Framing |
| Decision Factors | CFD- competitive research | v0.2 Competitive Landscape |
| Key Features | FEA- entries | v0.3 Feature Value Planning |
| Pricing Sensitivity | BR- pricing rules | v0.3 Pricing Model |
| Acquisition Channel | BR- targeting rules | v0.3 Moat Definition |
No link = No claim. If you can't cite evidence, the attribute is assumption, not fact.
Synthesis Process
-
Pull USER TYPE from v0.1 Problem Framing (CFD-)
- These are your candidate personas
-
Pull SEGMENTS from v0.2 Market Definition (CFD-, BR-)
- How is the market divided? Which segments are we targeting?
-
Pull TARGETING RULES from v0.3 Moat Definition (BR-)
- New-to-category vs. Switchers? Trigger moments?
-
Synthesize behavioral patterns from all CFD- evidence
- What goals unite this segment?
- What frustrations are consistent?
-
Map FEA- features to each persona
- Which features matter most to each?
- This informs journey mapping
-
Create PER- entries with full traceability
PER- Output Template
PER-XXX: [Persona Name]
Source IDs: [CFD-XXX, CFD-YYY, BR-ZZZ that inform this persona]
Type: [Primary | Secondary | Negative | Aspirational]
Segment: [From v0.2 market segment]
Demographics:
Role: [Job title / function]
Context: [Company size, industry, team structure]
Technical Level: [Novice | Intermediate | Expert]
Behavioral Profile:
Goals: [What they're trying to achieve — link to CFD- value]
Frustrations: [Current pain points — link to CFD- pain]
Decision Factors: [What influences their choices — link to CFD- research]
Current Workflow: [How they solve this today]
Product Relationship:
Primary Value: [CFD- value hypothesis they care about most]
Key Features: [FEA-XXX, FEA-YYY most relevant to them]
Pricing Sensitivity: [From BR- pricing rules]
Acquisition Channel: [How they'll find us — from BR- targeting]
Marketing Hook: [One-sentence pitch for this persona]
Example PER- entry:
PER-001: The Overwhelmed Ops Manager
Source IDs: CFD-003 (pain: manual tracking), CFD-012 (value: automation), BR-041 (target: switchers at renewal)
Type: Primary
Segment: SMB SaaS companies (10-50 employees)
Demographics:
Role: Operations Manager / Head of Ops
Context: Growing startup, wearing multiple hats, no dedicated tools budget
Technical Level: Intermediate (comfortable with SaaS, not a developer)
Behavioral Profile:
Goals: Reduce time spent on manual reporting (CFD-012)
Frustrations: Current tools require too much setup (CFD-003)
Decision Factors: Ease of use > feature count, must show ROI to CEO (CFD-025)
Current Workflow: Spreadsheets + manual data entry + weekly report compilation
Product Relationship:
Primary Value: CFD-012 ("Save 5 hours/week on reporting")
Key Features: FEA-001 (auto-sync), FEA-003 (one-click reports), FEA-007 (dashboard)
Pricing Sensitivity: BR-030 (SMB tier ≤$50/mo)
Acquisition Channel: BR-041 (target at contract renewal of competing tools)
Marketing Hook: "Stop building reports. Start using them."
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Persona explosion | >5 personas | Consolidate by behavior, not demographics |
| Fictional personas | No CFD- links | Every attribute needs evidence |
| Demographic-only | "25-35 year old male" | Focus on behaviors and goals |
| All personas are primary | "Everyone is important" | Rank by revenue potential |
| Copy-paste from competitors | Generic descriptions | Ground in YOUR research |
| Features without personas | Personas created but no FEA- links | Map features to who cares |
Quality Gates
Before proceeding to User Journey Mapping:
- Maximum 5 personas (ideally 1-3)
- At least one Primary persona defined
- Every persona has CFD- evidence links
- Key Features mapped from FEA- entries
- Acquisition Channel specified from BR- targeting
- Marketing Hook is specific and testable
Downstream Connections
PER- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.4 User Journey Mapping | Each UJ- references a PER- | UJ-001 is for PER-001 |
| v0.4 Screen Flow Definition | Persona context shapes UI | SCR-001 optimized for PER-001 tech level |
| v0.9 GTM | Marketing messaging per persona | Campaign targeting PER-002 segment |
| Sales Enablement | Persona-specific pitches | Discovery questions per PER- |
Detailed References
- Persona creation examples: See
references/examples.md - PER- entry template: See
assets/per.md
Screen Flow Definition
Position in workflow: v0.4 User Journey Mapping → v0.4 Screen Flow Definition → v0.5 Red Team Review
Screens are where journeys become tangible. This skill transforms user journeys into a screen inventory with navigation paths and feature mappings.
Consumes
This skill requires prior work from v0.3-v0.4:
- UJ-* user journey entries (from v0.4 User Journey Mapping) — Journey steps become screens; each step asks "What screen enables this action?"
- FEA-* feature entries (from v0.3 Features Value Planning) — Features map to screens showing which features appear on which screens
- PER-* persona entries (from v0.4 Persona Definition) — Persona context (technical level, role) shapes screen design choices and complexity
- MVP-SCOPE artifact (from v0.3 Features Value Planning) — Explicit feature boundary; screens must render only MVP-scoped features, backlog features deferred
- BR-* business rules (from v0.3 Commercial Model) — Constraints affecting screen layout (pricing tier rules affect which settings appear, role-based visibility, data refresh rates, etc.)
This skill assumes v0.4 User Journey Mapping is complete.
Produces
This skill creates/updates:
- SCR-* entries (screens, confidence 2-3/5) — Screen inventory with journey/feature/persona mappings showing purpose, actions, navigation, and constraints
- DES-* entries (design system components, confidence 2-3/5) — Reusable UI elements and patterns identified across screens
- Feature-to-Screen matrix — Validation artifact showing every FEA- and every UJ- step mapped to SCR-
- Screen count and complexity assessment — Critical for v0.5 technical stack selection (number of screens informs frontend framework needs)
All SCR- entries should include:
confidence: 2-3/5(based on journey validation and feature implementation status)- Evidence source citations (UJ-ID, FEA-ID, PER-ID references)
- Forward target: "Would move to 4/5 if validated in wireframe review or prototype testing"
Example SCR- entry with confidence:
SCR-001: Main Dashboard
Type: Page
Purpose: Central hub showing key metrics and quick actions
Journeys: UJ-001 (Step 4), UJ-002 (Step 5), UJ-003 (Step 1)
Features: FEA-007 (dashboard), FEA-003 (reports preview), FEA-012 (notifications) — all in MVP-SCOPE
Confidence: 2/5 (source: journey-mapping + design-validation; not yet wireframed)
Primary Actions: Create Report, View Data Sources, Access Settings
Secondary Actions: Invite Team, View Help
Navigation:
From: SCR-000 (Login), any screen via nav bar
To: SCR-002 (Report Builder), SCR-003 (Data Sources), SCR-010 (Settings)
Content:
- Key metrics summary (3-5 cards) → DES-001 (Data Card)
- Recent reports list → DES-002 (Report List)
- Data source health status → DES-003 (Status Badge)
- Notification bell → FEA-012
Constraints: BR-015 (data refresh rate), BR-020 (role-based visibility)
Design Notes: PER-001 needs "busy dashboard" - show progress at a glance without overwhelming
Next Target: "Would move to 4/5 if wireframe validated with 3+ target personas"
Example DES- entry with confidence:
DES-001: Data Card
Type: Component
Used In: SCR-001 (Dashboard), SCR-005 (Analytics)
Purpose: Display single metric with trend indicator
Confidence: 2/5 (source: design-pattern-research; component not yet coded)
States:
- Default: Shows value + trend arrow
- Loading: Skeleton placeholder
- Empty: "No data yet" message
- Error: "Failed to load" with retry
Variants: Small (dashboard, 120px width), Large (detail view, 240px width)
Accessibility: ARIA labels for trend direction, keyboard navigation support
Next Target: "Would move to 4/5 if implemented and tested across both use cases"
Screen Types
| Type | Definition | Design Priority | Example |
|---|---|---|---|
| Page | Full viewport, primary navigation target | High | Dashboard, Settings |
| Modal | Overlay, blocks underlying page | Medium | Confirmation, Quick Edit |
| Panel | Slide-out, contextual detail | Medium | Detail View, Filters |
| Component | Reusable UI element | Varies | Header, Data Table |
Rule: Start with Pages, then identify where Modals/Panels reduce navigation friction.
Navigation Patterns
Choose a pattern based on product type:
| Pattern | When to Use | Example Products |
|---|---|---|
| Hub & Spoke | Dashboard-centric apps | Analytics, CRM |
| Linear Flow | Wizard/checkout processes | Onboarding, E-commerce |
| Hierarchical | Content-heavy apps | Documentation, CMS |
| Flat | Simple single-purpose apps | Timer, Calculator |
Most SaaS products use Hub & Spoke with occasional Linear Flows for onboarding/purchase.
Mapping Process
-
Pull UJ- (journeys) and FEA- (features) from prior steps
- Journeys define the paths; features define the capabilities
-
Inventory unique screens needed across all journeys
- Walk through each journey step and ask: "What screen does this happen on?"
-
Map features to screens (many:many relationship)
- One feature may appear on multiple screens
- One screen may contain multiple features
-
Define navigation structure
- How do users get from screen to screen?
- What's the hierarchy? What's always accessible?
-
Identify shared components
- Headers, footers, navigation bars
- Common patterns: data tables, forms, cards
-
Create SCR- entries with journey and feature traceability
-
Create DES- entries for design system elements
SCR- Output Template
SCR-XXX: [Screen Name]
Type: [Page | Modal | Panel | Component]
Purpose: [What user accomplishes on this screen]
Journeys: [UJ-XXX, UJ-YYY that use this screen]
Features: [FEA-XXX, FEA-YYY rendered on this screen]
Primary Actions: [Key user actions available]
Secondary Actions: [Less common but available actions]
Navigation:
From: [SCR-XXX, SCR-YYY — how users arrive]
To: [SCR-XXX, SCR-YYY — where users can go next]
Content:
- [Data/element 1]
- [Data/element 2]
Constraints: [BR-XXX rules affecting this screen]
Design Notes: [Persona-specific considerations from PER-]
Example SCR- entry:
SCR-001: Main Dashboard
Type: Page
Purpose: Central hub showing key metrics and quick actions
Journeys: UJ-001 (Step 4), UJ-002 (Step 5), UJ-003 (Step 1)
Features: FEA-007 (dashboard), FEA-003 (reports preview), FEA-012 (notifications)
Primary Actions: Create Report, View Data Sources, Access Settings
Secondary Actions: Invite Team, View Help
Navigation:
From: SCR-000 (Login), any screen via nav bar
To: SCR-002 (Report Builder), SCR-003 (Data Sources), SCR-010 (Settings)
Content:
- Key metrics summary (3-5 cards)
- Recent reports list
- Data source health status
- Notification bell
Constraints: BR-015 (data refresh rate), BR-020 (role-based visibility)
Design Notes: PER-001 needs "busy dashboard" - show progress at a glance
DES- Output Template
DES-XXX: [Component/Pattern Name]
Type: [Component | Pattern | Layout]
Used In: [SCR-XXX, SCR-YYY]
Purpose: [What this element does]
States:
- Default: [Normal state]
- Loading: [When fetching data]
- Empty: [No data state]
- Error: [Error state]
- Disabled: [When not interactive]
Variants: [If multiple versions exist]
Accessibility: [A11y considerations]
Example DES- entry:
DES-001: Data Card
Type: Component
Used In: SCR-001 (Dashboard), SCR-005 (Analytics)
Purpose: Display single metric with trend indicator
States:
- Default: Shows value + trend arrow
- Loading: Skeleton placeholder
- Empty: "No data yet" message
- Error: "Failed to load" with retry
Variants: Small (dashboard), Large (detail view)
Accessibility: ARIA labels for trend direction
Screen Categories
Organize screens by function:
| Category | Examples | Design Priority |
|---|---|---|
| Entry Points | Login, Landing, Signup | High (first impressions) |
| Core Workflow | Main task screens | High (value delivery) |
| Settings/Admin | Preferences, Account, Billing | Medium (necessary) |
| Support/Help | Docs, Contact, FAQ | Low (failure recovery) |
Rule: Invest design effort proportional to priority. Don't over-design settings screens.
Feature-to-Screen Matrix
Create a mapping matrix:
| Feature | SCR-001 | SCR-002 | SCR-003 | SCR-004 |
|---|---|---|---|---|
| FEA-001 (auto-sync) | ✓ | |||
| FEA-003 (reports) | Preview | Full | ||
| FEA-007 (dashboard) | ✓ | |||
| FEA-010 (auth) | ✓ |
This reveals:
- Features spread across multiple screens (normal)
- Features on no screens (problem: orphaned)
- Screens with no features (problem: unnecessary)
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Screen explosion | >20 unique screens for MVP | Consolidate; use modals/panels instead |
| Feature-per-screen | 1:1 FEA to SCR mapping | Group related features on screens |
| No shared components | Every screen is unique | Extract DES- patterns |
| Navigation dead-ends | Can't get back from a screen | Ensure bidirectional paths |
| Journey disconnect | SCR- not tied to UJ- | Every screen serves a journey |
| Modal abuse | Everything is a modal | Modals for confirmations/quick edits only |
Quality Gates
Before proceeding to v0.5 Red Team Review:
- All UJ- steps mapped to screens
- All FEA- features appear on at least one screen
- Navigation paths are bidirectional (no dead-ends)
- Shared components identified as DES- entries
- Screen count reasonable for MVP (<15 pages)
- Entry points and core workflow prioritized
Downstream Connections
SCR- and DES- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.5 Technical Stack Selection | Screen complexity informs frontend needs | "20 screens → need component library" |
| v0.6 Technical Specification | Screens inform API data needs | SCR-001 → API-001 (dashboard data) |
| v0.7 Build Execution | Screens become implementation tasks | EPIC-03 builds SCR-001–005 |
| Design | SCR- entries become wireframes/mockups | SCR-001 → Figma design |
Detailed References
- Screen flow examples: See
references/examples.md - SCR- entry template: See
assets/scr.md - DES- entry template: See
assets/des.md - Navigation patterns guide: See
references/navigation-patterns.md
User Journey Mapping
Position in workflow: v0.4 Persona Definition → v0.4 User Journey Mapping → v0.4 Screen Flow Definition
User journeys transform features into paths. A journey answers: "How does [persona] go from [trigger] to [value moment] using [features]?"
Consumes
This skill requires prior work from v0.3-v0.4:
- PER-* persona entries (from v0.4 Persona Definition) — Behavioral profiles that journeys are built around; each journey belongs to a specific persona
- FEA-* feature entries (from v0.3 Features Value Planning) — Feature list that becomes journey steps; validates that journeys use only MVP-scoped features
- KPI-* outcome definitions (from v0.3 Outcome Definition) — Success metrics that journeys drive; Core journeys must tie to Tier 1/2 KPIs
- MVP-SCOPE artifact (from v0.3 Features Value Planning) — Explicit feature boundary; journeys must use only features in MVP-SCOPE, no backlog features
- BR-* business rules (from v0.3 Commercial Model) — Constraints that affect journey design (pricing tiers affect onboarding paths, moat rules affect targeting journeys, etc.)
This skill assumes v0.4 Persona Definition is complete.
Produces
This skill creates/updates:
- UJ-* entries (user journeys, confidence 2-3/5) — Paths from trigger through steps to value moment, tied to PER-/FEA-/KPI- with pain point identification
- Journey sequencing artifact — Dependency map showing which journeys gate which (Onboarding gates Core; Core gates Power User)
All UJ- entries should include:
confidence: 2-3/5(based on design validation and feature implementation certainty)- Evidence source citations (PER-ID, FEA-ID, KPI-ID references)
- Forward target: "Would move to 4/5 if validated in beta with actual persona users"
Example UJ- entry with confidence:
UJ-001: First Report Generation
Persona: PER-001 (Overwhelmed Ops Manager)
Type: Core
Trigger: User completes onboarding and sees empty dashboard
Goal: Generate first automated report to see time-saving value
Confidence: 2/5 (source: design-validation + feature-status-in-development; KPI-002 links to conversion)
Steps:
1. Click "Create Report" → FEA-003 (one-click reports) [In MVP-SCOPE]
2. Select data source → FEA-001 (auto-sync) [In MVP-SCOPE]
3. Choose report template → FEA-008 (templates) [In MVP-SCOPE]
4. Preview report → FEA-003 [In MVP-SCOPE]
5. Export/share report → FEA-009 (export) [In MVP-SCOPE]
Pain Points:
- Step 2: User may not have connected data source yet (dependency on UJ-002)
- Step 3: Template overload if too many choices (design concern; recommend 3-5 templates max)
Moment of Value: Seeing the completed report with their actual data
KPI Link: KPI-002 (activation rate — user completes first valuable action)
Success Metric: Time from "Create Report" click to export ≤ 5 minutes
Dependencies: BR-015 (data format rules), UJ-002 (data source connection must precede)
Next Target: "Would move to 4/5 if 5+ beta users complete this journey in ≤5 minutes and report value"
Journey Types
| Type | Purpose | Priority Signal | Example |
|---|---|---|---|
| Core | Primary value delivery | Must complete for activation | First report generated |
| Onboarding | First-time user setup | Blocks all other journeys | Account creation → first action |
| Recovery | Error handling, support | Retention protection | Password reset, billing issue |
| Power User | Advanced workflows | Expansion/upsell | Bulk operations, integrations |
Rule: Define Onboarding first (it gates everything), then Core journeys (they deliver KPI-), then others.
Journey Anatomy
Every journey has:
- Trigger — What causes the user to start? (Event, not "opens app")
- Steps — Actions linked to FEA- features
- Pain Points — Where friction exists (design around these)
- Moment of Value — When user achieves goal (this drives KPI-)
Mapping Process
-
Pull PER- (personas) from Persona Definition
- Each journey belongs to a specific persona
-
Pull FEA- (features) and KPI- (outcomes) from v0.3
- Features are the building blocks of journey steps
- KPIs tell you which journeys matter most
-
Define trigger events
- What causes the user to start this journey?
- Be specific: "Receives calendar invite" not "opens app"
-
Map step flow using features
- Each step = an action the user takes
- Link each step to the FEA- that enables it
-
Identify pain points
- Where might the user get confused, frustrated, or blocked?
- These inform UX design decisions
-
Mark "moments of value"
- When does the user get the payoff?
- This should tie to KPI- measurement
-
Create UJ- entries with full traceability
UJ- Output Template
UJ-XXX: [Journey Title]
Persona: [PER-XXX]
Type: [Core | Onboarding | Recovery | Power User]
Trigger: [Event that initiates journey]
Goal: [What user wants to accomplish]
Steps:
1. [Action] → FEA-XXX
2. [Action] → FEA-XXX
3. [Action] → FEA-XXX
...
Pain Points:
- [Step X]: [Potential friction — e.g., "requires context switch"]
- [Step Y]: [Potential friction]
Moment of Value: [When user achieves goal — be specific]
KPI Link: [KPI-XXX this journey drives]
Success Metric: [How we measure journey completion]
Dependencies: [BR-XXX constraints, API-XXX if known]
Example UJ- entry:
UJ-001: First Report Generation
Persona: PER-001 (Overwhelmed Ops Manager)
Type: Core
Trigger: User completes onboarding and sees empty dashboard
Goal: Generate first automated report to see time-saving value
Steps:
1. Click "Create Report" → FEA-003 (one-click reports)
2. Select data source → FEA-001 (auto-sync)
3. Choose report template → FEA-008 (templates)
4. Preview report → FEA-003
5. Export/share report → FEA-009 (export)
Pain Points:
- Step 2: User may not have connected data source yet (dependency on UJ-002)
- Step 3: Template overload if too many choices
Moment of Value: Seeing the completed report with their actual data
KPI Link: KPI-002 (activation rate)
Success Metric: Time from "Create Report" click to export ≤ 5 minutes
Dependencies: BR-015 (data format rules), UJ-002 (data source connection)
Feature-to-Journey Validation
After mapping journeys, validate:
- No orphaned features: Every FEA- appears in at least one UJ-
- No journey gaps: Every step has a FEA- that enables it
- KPI coverage: Core journeys tie to Tier 1/2 KPIs
If a FEA- isn't in any journey, either:
- Add it to a journey (you missed a use case), or
- Cut it from scope (it's not needed)
Journey Sequencing
Map dependencies between journeys:
UJ-000: Onboarding (gates all)
↓
UJ-001: First Report (Core) ← KPI-002 (activation)
↓
UJ-002: Data Source Connection (Core) ← KPI-003 (depth)
↓
UJ-003: Team Invite (Power User) ← KPI-004 (expansion)
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Feature-first journeys | Steps = feature list dumped in order | Start with user goal, then map features to it |
| No trigger | "User opens app" | Define specific event: "receives notification" |
| No value moment | Journey ends without payoff | Each journey needs clear outcome |
| Orphaned features | FEA- not in any journey | Add to journey or cut from scope |
| Generic personas | "User does X" | Specify PER-: "PER-001 does X" |
| Happy path only | No pain points identified | Anticipate where users struggle |
| Mega-journeys | 15+ steps | Split into sub-journeys |
Quality Gates
Before proceeding to Screen Flow Definition:
- Onboarding journey defined first
- All Core journeys mapped to KPI-
- Every FEA- appears in at least one journey
- Every journey has a specific trigger (not "opens app")
- Pain points identified for friction design
- Journey dependencies documented
Downstream Connections
UJ- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.4 Screen Flow Definition | Steps become screens | UJ-001 Step 3 → SCR-005 |
| v0.6 Technical Specification | Journeys inform API sequences | UJ-001 → API-001, API-002 flow |
| v0.7 Test Planning | Journeys become E2E tests | TEST-020 validates UJ-001 |
| v0.9 GTM | Journey-based onboarding messaging | "Complete [UJ-001] in 5 minutes" |
Detailed References
- Journey mapping examples: See
references/examples.md - UJ- entry template: See
assets/uj.md - Journey sequencing guide: See
references/sequencing.md
Visual Prototype Gate
Position in workflow: v0.4 Screen Flow Definition → v0.4 Visual Prototype Gate → v0.5 Red Team Review
Screens on paper are hypotheses. Screens rendered visually are testable. This skill converts SCR- entries into structured prompts for Google Stitch (or any UI generation tool), then captures feedback routed back to specific SoT IDs.
Rule: No product advances past v0.4 without a visual prototype reviewed by at least one stakeholder.
Consumes
- SCR-* entries (from Screen Flow Definition) — Each SCR- becomes one Stitch prompt. 1:1 mapping, no exceptions.
- PER-* entries (from Persona Definition) — User context shapes copy, complexity, and emotional framing per screen.
- UJ-* entries (from User Journey Mapping) — Journey position determines each screen's emotional beat (uncertainty → clarity → confidence).
- DES-* entries (from Screen Flow Definition) — Shared components referenced in prompts for visual consistency.
- BR-* business rules — Constraints affecting visual layout (pricing tiers, role-based visibility, data rules).
Produces
- Stitch Prompt Block per SCR- — One structured prompt per screen, ready to paste into Stitch. Grouped by UJ- journey for context.
- Prototype Context Brief — Product context + design style preamble (pasted once into Stitch before screen prompts).
- Feedback Capture Template — Table mapping each prototype screen to its SCR- ID for structured review. See
assets/feedback-capture-template.md. - No new SoT IDs — This skill visualizes existing IDs. Feedback routes back to SCR-, DES-, or CFD- entries.
Step-by-Step Process
Step 1: Confirm Inputs Exist
Check that Screen Flow Definition is complete:
- At least 3 SCR- entries exist with Purpose, Key Elements, and Related IDs populated
- At least 1 UJ- journey references those screens
- Design style preference confirmed with user (or default: "Clean B2B SaaS, minimal, professional")
If SCR- entries are incomplete, stop and run prd-v04-screen-flow-definition first.
Step 2: Write the Prototype Context Brief
One block, written once per product. This is pasted into Stitch as the opening context before individual screen prompts.
PRODUCT CONTEXT
[2-3 sentences from PRD v0.1 Spark: what the product is, who uses it, what pain it solves]
PRIMARY USER
[From PER-001: role, context, technical comfort level]
DESIGN STYLE
[Confirmed aesthetic — e.g., "Clean B2B SaaS, dark sidebar, minimal. Color for status only."]
Step 3: Generate Per-Screen Prompts
For each SCR- entry, produce one Stitch prompt block. Follow this template:
SCREEN: [SCR-XXX] — [Screen Name]
Journey position: [UJ-XXX], Step [N] of [Total]
User goal: [From SCR- Purpose field]
Situation: [What just happened — derived from prior UJ- step]
Key UI elements: [From SCR- Key Elements, using specific UI/UX keywords]
- [Element 1: be specific — "green 'Run' button, top right, disabled until selection made"]
- [Element 2: reference DES-XXX if shared component]
- [Element 3+]
Constraints: [BR-XXX rules affecting this screen — e.g., "free tier sees max 3 items"]
Emotional beat: [Derived from journey position — early=uncertainty, mid=engagement, end=confidence]
Layout: [UI surface type — full page, sidebar panel, modal, card grid, etc.]
Stitch-specific guidance (from research):
- Use UI/UX keywords: "navigation bar," "card layout," "call-to-action," not vague terms like "a button"
- One screen per Stitch generation for best results — do not combine multiple SCR- entries into one prompt
- Include adjectives for aesthetic: "minimal," "clean," "dark," "warm" — Stitch uses these for palette and typography
- Reference specific positions: "top-right," "below the header," "spanning full width"
Step 4: Identify the Money Shot
Select the single screen that communicates core product value fastest. This is typically the screen at the UJ- "Moment of Value" step. Mark it in the output. This frame gets screenshotted for any stakeholder deck, landing page, or pitch.
Step 5: Output Feedback Capture Template
Alongside prompts, output the feedback capture template (see assets/feedback-capture-template.md). This is the structured review artifact — reviewers annotate per-screen, feedback routes to specific IDs.
Stitch Workflow Notes
Google Stitch iterates best with incremental refinement:
- Paste the Prototype Context Brief first
- Generate one screen at a time using per-screen prompts
- Refine each screen with targeted follow-ups ("Move the CTA to the right," "Change card layout to 2-column grid")
- Export to Figma if design iteration continues beyond prototype stage
For non-Stitch tools, see references/tool-adaptation-notes.md.
Quality Gates (v0.4 → v0.5 Readiness)
Before proceeding to v0.5 Red Team Review:
- All SCR- entries have a corresponding visual prototype screen
- At least one stakeholder has reviewed the prototype
- Feedback Capture Template is completed with disposition for each item
- Money Shot identified and captured
Downstream Connections
| Consumer | What It Uses |
|---|---|
| v0.5 Red Team Review | Visual prototype informs risk assessment — "does this feel buildable?" |
| v0.6 Architecture | Validated screens inform API data requirements |
| v0.7 Build Execution | Prototype becomes the visual spec for implementation |
| Stakeholder Communication | Money Shot used in decks, pitches, landing pages |
Detailed References
- Feedback capture template: See
assets/feedback-capture-template.md - Tool adaptation notes: See
references/tool-adaptation-notes.md - Screen count guidelines: See
references/screen-count-guidelines.md
Risk Discovery Interview
Position in workflow: v0.4 Screen Flow Definition → v0.5 Risk Discovery Interview → v0.5 Technical Stack Selection
This is an interactive interview skill. The AI asks questions, the user reflects and decides. The goal is to surface risks so the user can mitigate or accept them—not to kill ideas.
Consumes
This skill requires prior work from v0.1-v0.4:
- CFD-* all customer feedback entries (from v0.1-v0.2) — User research foundation; reveals confidence tier in market assumptions
- BR-* all business rules (from v0.2-v0.3) — Constraints on what can change (pricing, moat, product type constrain risk responses)
- FEA-* feature entries (from v0.3) — Feature complexity and priorities signal technical risks
- PER-* persona entries (from v0.4) — Persona distribution and behaviors reveal adoption risks and churn signals
- UJ-* journey entries (from v0.4) — Journey complexity signals friction points; long journeys increase adoption risk
- SCR-* screen entries (from v0.4) — Screen count and design complexity informs technical resource risk
This skill assumes v0.1-v0.4 work is complete and serves as context for interview discovery.
Produces
This skill creates/updates:
- RISK-* entries (risk discovery, owner-assigned severity) — Identified risks with Impact/Likelihood scoring (raw score from 1-9), response type (Mitigate/Accept/Avoid/Transfer), specific mitigations, and owners
- README Risk Scorecard — Baseline risk profile aggregated by category (Market/User/Technical) with total scores and risk level assessment
- Risk mitigation summary — Top 3-5 risks requiring active mitigation before v0.6 architecture work
All RISK- entries are created through user decision during the interview; they reflect explicit owner choices on severity, not AI assumptions:
Example RISK- entry (user-scored):
RISK-001: Market — Competitor Feature Parity
Description: Competitor X launches report scheduling feature (our FEA-003 planned) within 60 days
Trigger: Competitor announces roadmap; sees our landing page
Impact: High (3) — User severity assessment based on competitive urgency
Likelihood: Medium (2) — User assessment of competitor execution speed
Raw Score: 6 (3 × 2)
Status: open
Effective Score: 6.0
Early Signal: Competitor job postings for feature area, beta announcement
Response: Mitigate
Mitigation: Accelerate FEA-003 launch by 30 days; add scheduling as P0 (links to FEA-003, KPI-002)
Owner: Product Lead
Linked IDs: FEA-003 (report scheduling), KPI-002 (activation rate), BR-042 (undercut positioning)
Review Date: Weekly during v0.6 (architecture phase)
Added: v0.5
Note: Confidence scores are NOT part of RISK- entries. Risks are binary facts (discovered or not); severity is user-decided. Confidence applies to CFD-/FEA-/KPI- entries, not risks.
Design Principles
- Interview, not inquisition — Facilitate discovery, don't interrogate
- Inform, not kill — Surface risks so user can mitigate, not abandon
- User owns decisions — AI facilitates, user assigns severity and response
- Actionable outputs — Every risk has a mitigation path or explicit "accept"
Risk Categories
Discovery Categories (Interview Prompts)
| Category | Focus Area | Example Questions |
|---|---|---|
| Market | Competitors, timing, demand | "What if [competitor] launches this feature next month?" |
| Technical | Complexity, unknowns, dependencies | "Which feature has the most technical uncertainty?" |
| Adoption | User behavior, activation, retention | "What's the biggest friction point in onboarding?" |
| Resource | Team, budget, time | "If you had to cut scope by 50%, what stays?" |
| Dependency | External factors, integrations, partners | "What external factor could block launch?" |
| Timing | Deadlines, market windows, seasonality | "Is there a deadline we must hit? Why?" |
Scoring Categories (README Scorecard)
Each RISK- entry maps to one of 3 scoring categories for the README Risk Scorecard:
| Scoring Category | Discovery Categories | Measures |
|---|---|---|
| Market | Market, Timing | Will anyone buy this? |
| User | Adoption, Dependency | Will users succeed with this? |
| Technical | Technical, Resource | Can we build and run this? |
Interview Flow
Phase 1: Context Review
Before asking questions, AI reviews:
- CFD- evidence from v0.1-v0.2
- FEA- features and their priorities
- UJ- journeys and their complexity
- BR- business rules and constraints
Phase 2: Guided Questions
Ask questions from each category, adapting based on product context:
Market Risks:
- "What happens if [competitor] launches something similar in 60 days?"
- "What market assumption are you least confident about?"
- "What would cause users to choose a competitor instead?"
Technical Risks:
- "Which feature has the most technical uncertainty?"
- "What technology choice are you least confident about?"
- "Is there anything you've never built before?"
Adoption Risks:
- "What's the biggest friction point in [UJ-001 onboarding journey]?"
- "What behavior change are you asking users to make?"
- "What would cause a user to churn in the first week?"
Resource Risks:
- "If you had only 2 developers, what would you cut?"
- "What skill does the team lack?"
- "What's your runway for validation?"
Dependency Risks:
- "What external API or service could break your product?"
- "What partner relationship is critical?"
- "What regulatory requirement could block launch?"
Timing Risks:
- "Is there a hard deadline? What happens if you miss it?"
- "Is there a market window closing?"
- "What seasonal factor affects launch timing?"
Phase 3: Risk Documentation
For each identified risk, create RISK- entry with user input on severity and response.
Phase 4: Priority & Review
- Force-rank risks by Impact × Likelihood
- Identify top 3-5 that require active mitigation
- Document "accept" decisions explicitly
Interview Techniques
| Technique | How to Use | When to Use |
|---|---|---|
| Pre-mortem | "It's 6 months from now and the product failed. Why?" | Opening question |
| Constraint forcing | "If you only had [X], what would you cut?" | Resource discovery |
| Dependency mapping | "What external factor could block launch?" | Dependency discovery |
| Assumption surfacing | "What must be true for this to work?" | Any category |
| Devil's advocate | "Let me argue the opposite—what if [X]?" | Challenge weak evidence |
RISK- Output Template
RISK-XXX: [Risk Title]
Scoring Category: [Market | User | Technical]
Discovery Category: [Market | Technical | Adoption | Resource | Dependency | Timing]
Description: [What could go wrong]
Trigger: [What would cause this to happen]
Impact: [High | Medium | Low] — User assessed
Likelihood: [High | Medium | Low] — User assessed
Raw Score: [Impact × Likelihood, 1-9]
Status: [open | mitigating | mitigated | resolved | accepted]
Effective Score: [Raw Score × Status Weight]
Early Signal: [How we'd know this is happening]
Response: [Mitigate | Accept | Avoid | Transfer]
Mitigation: [Specific action if Response = Mitigate]
Owner: [Who is responsible for monitoring]
Linked IDs: [FEA-XXX, UJ-XXX, BR-XXX affected]
Review Date: [When to reassess this risk]
Added: [PRD stage when discovered, e.g., v0.5]
Status weights: open=1.0, accepted=1.0, mitigating=0.5, mitigated=0.25, resolved=0.0
Example RISK- entry:
RISK-001: Primary API Dependency (Stripe) Outage
Scoring Category: Technical
Discovery Category: Dependency
Description: Stripe API outage would block all payment processing
Trigger: Stripe infrastructure failure or rate limiting
Impact: High (3) — All revenue blocked during outage
Likelihood: Low (1) — Stripe has 99.99% uptime SLA
Raw Score: 3
Status: mitigating
Effective Score: 1.5
Early Signal: Stripe status page, payment failure rate spike
Response: Mitigate
Mitigation:
- Implement graceful degradation (queue payments for retry)
- Add status page monitoring alert
- Document manual billing fallback process
Owner: Tech Lead
Linked IDs: FEA-020 (payments), UJ-005 (checkout), BR-030 (pricing)
Review Date: Before launch, quarterly thereafter
Added: v0.5
Risk Response Types
| Response | When to Use | Example |
|---|---|---|
| Mitigate | Can reduce impact or likelihood | Add fallback provider, implement retry logic |
| Accept | Low impact or unavoidable | "Competitor might copy us—we accept" |
| Avoid | Change plan to eliminate risk | Remove feature with high technical uncertainty |
| Transfer | Someone else owns the risk | Use managed service instead of self-hosting |
Severity Matrix
| Low Impact | Medium Impact | High Impact | |
|---|---|---|---|
| High Likelihood | Monitor | Mitigate | Mitigate urgently |
| Medium Likelihood | Accept | Monitor/Mitigate | Mitigate |
| Low Likelihood | Accept | Accept/Monitor | Monitor |
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Risk theater | 50+ risks documented | Focus on top 10 that matter |
| All high severity | Everything is critical | Force rank; max 3-5 "High" |
| No owner | Risks without accountability | Every RISK- needs an owner |
| Mitigation = "be careful" | Vague responses | Require specific, testable actions |
| Interview becomes lecture | AI talks more than user | Ask, listen, summarize |
| Killing ideas | Every risk leads to "don't do it" | Frame as "how to succeed despite" |
Phase 5: Score & Scorecard
After documenting all risks:
- Assign scoring categories: Map each RISK- to Market, User, or Technical
- Calculate scores: Raw Score = Impact × Likelihood; Effective = Raw × Status Weight (all start as
open) - Sum by category: Add effective scores within each scoring category
- Determine risk level: Total score → Low (0-12), Moderate (13-25), Elevated (26-40), High (41+)
- Update README scorecard: Fill in the Risk Scorecard table in README.md
Quality Gates
Before proceeding to Technical Stack Selection:
- All 6 risk categories explored
- Maximum 10-15 RISK- entries (focused, not exhaustive)
- Force-ranked by priority (Impact × Likelihood)
- Top 5 risks have specific mitigation plans
- "Accept" decisions are explicit, not accidental
- Every RISK- has an owner
- Every RISK- has a scoring category (Market/User/Technical)
- README Risk Scorecard updated with baseline scores
Continuous Risk Management
v0.5 establishes the baseline risk register, but risk discovery does not end here. New RISK- entries can be added at any stage:
| Stage | Typical New Risks | Score Impact |
|---|---|---|
| v0.6 Architecture | Infrastructure complexity, integration unknowns | Technical score rises |
| v0.7 Build | Implementation blockers, test coverage gaps | Technical score rises |
| v0.8 Deployment | Operational risks, security findings | Technical score rises |
| v0.9 GTM | Market timing shifts, competitive moves | Market score rises |
| v1.0 Growth | Real adoption data contradicting assumptions | User score rises |
Protocol when adding risks after v0.5:
- Use the same RISK- template (assign next available number)
- Set
Added: v0.Xto record which stage surfaced it - Recalculate category and total scores
- Update README Risk Scorecard
Protocol when risk status changes:
- Update the RISK- entry status in PRD.md
- Recalculate effective score (Raw × new Status Weight)
- Update README Risk Scorecard totals
Downstream Connections
RISK- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| README Risk Scorecard | Aggregated scores by category | Total score determines project risk level |
| v0.5 Technical Stack Selection | RISK- constraints affect tech choices | RISK-003 (latency) → choose edge hosting |
| v0.6 Architecture Design | Risk mitigations become architecture requirements | RISK-005 → add circuit breaker |
| v0.7 Build Execution | Risk monitoring in EPIC | Track RISK-001 early signals |
| KPI- Thresholds | Kill criteria from risks | "If RISK-002 triggers, evaluate pivot" |
Detailed References
- Interview question bank: See
references/question-bank.md - RISK- entry template: See
assets/risk.md - Example risk register: See
references/examples.md
Technical Stack Selection
Make technology decisions for every capability your product needs — starting with what you already have, then evaluating what fits, then deciding what to build.
Position in workflow: v0.5 Risk Discovery Interview → v0.5 Technical Stack Selection → v0.6 Architecture Design
Consumes
This skill requires prior work from v0.3-v0.5:
- FEA-* feature entries (from v0.3 Features Value Planning) — Every feature translates to technical capability requirements; derives which capability areas need technology decisions
- SCR-* screen entries (from v0.4 Screen Flow Definition) — Screen count and component complexity informs frontend technology needs; DES- components reveal design system constraints
- RISK-* risk entries (from v0.5 Risk Discovery Interview) — RISK- constraints directly affect technology choices (RISK-003: latency → choose edge hosting; RISK-004: compliance → choose HIPAA-ready provider)
- Existing TECH-* entries (from prior products if brownfield) — If product family exists, inherited technology decisions constrain new choices
- Product family information (from user discovery if brownfield) — Shared infrastructure, existing databases, established frameworks narrow the evaluation space
This skill assumes v0.5 Risk Discovery Interview is complete and FEA-/SCR-/RISK- entries provide the constraint foundation.
Produces
This skill creates/updates:
- TECH-* entries (technology decisions, decision type + rationale) — Decisions for each capability area with categories (Reuse/Extend/New/Replace), options considered, choice made, and rationale tied to FEA-/RISK- constraints
- Risk-to-Technology mapping table — Validation showing every RISK- entry has corresponding TECH- response or explicit acceptance
- Technical feasibility artifact — Confidence assessment on whether technology choices support feature MVP-SCOPE and risk mitigations
All TECH- entries should include:
- Decision Category: Reuse/Extend/New/Replace/Build/Buy/Integrate/Research
- Features Served: FEA-XXX references (every TECH- must serve at least one feature)
- Risk Constraints: RISK-XXX references (if any risks constrain this decision)
- Rationale: Why this choice; trade-offs considered
- Cost Assessment: Current stage cost AND 10x scale cost for Buy decisions (MVP stage: prioritize speed and quality, not optimization)
Example TECH- entry (Buy decision with RISK constraint):
TECH-003: Authentication & Authorization
Decision Category: Buy (managed service)
Features Served: FEA-010 (user auth), FEA-020 (role-based access control) — both in MVP-SCOPE
Risk Constraints: RISK-005 (security: we have no in-house security expertise), RISK-008 (compliance: need SOC2 certification path)
Choice: Clerk (platform auth)
Rationale:
- Reduces security surface (RISK-005 mitigation: no password storage, no token handling)
- Provides SOC2 compliance path (RISK-008 mitigation)
- Includes MFA, passwordless, social login; UI handles all FEA-010 requirements without build
- 30 day free tier; $25–$500/mo at growth stage (acceptable for MVP runway)
Trade-offs:
- Plus: Zero auth code to maintain; future-proofs as compliance requirements evolve
- Minus: Vendor lock-in; customer data in Clerk's tables (acceptable for SMB stage)
Cost:
- MVP stage (0–10k users): ~$50–200/mo (free tier covers launch)
- 10x scale (100k users): ~$500–2000/mo (still cheaper than building in-house team)
Product Family Notes: If sibling products exist, Clerk can SSO across them using shared realm config (document in shared infrastructure EPIC)
Alternatives Considered:
- Firebase Auth: Similar, but tighter Google lock-in and slightly higher cost at scale
- Auth0: Too expensive for MVP stage; better for enterprise products
- Build custom: Rejected — RISK-005 says we lack in-house security expertise; not a differentiator
Next Step: If TECH-005 (Research: custom data encryption) decides to build, reconsider Auth0 for compliance sync
Example TECH- entry (Reuse decision from brownfield):
TECH-001: Frontend Framework
Decision Category: Reuse
Features Served: FEA-006 (dashboard), FEA-007 (reports), all screen components — every UI in MVP-SCOPE
Risk Constraints: None (no frontend risk identified)
Existing Asset: React + Next.js (running in sibling product since 2023)
Rationale:
- Already deployed, proven stable at 50k users
- Team expertise established; no learning curve
- Incremental cost: just new feature builds, no framework evaluation/migration risk
- Shared component library available (DES-001–005 can import existing primitives)
Cost: $0 incremental (infrastructure already paid)
Product Family Notes: Share component library and auth context across products using monorepo structure (document in shared infrastructure EPIC)
Workflow Overview
- Discover Existing Assets → Read SOT or interview user for current tech stack
- Categorize Layers → Reuse / Extend / New / Replace for each capability
- Evaluate Vendor Fit → Check vendor options for New/Replace layers (if constraints exist)
- Evaluate Alternatives → Research non-vendor options where gaps exist
- Check Product Family → Shared infrastructure, component reuse, cross-product UX
- Create TECH- Entries → Write entries using standard or reuse template
- Map to Risks → Cross-reference every TECH- entry with RISK- constraints
Decision Categories
| Category | Definition | When to Choose |
|---|---|---|
| Reuse | Existing asset covers this need as-is | Sibling product or prior work already solves this |
| Extend | Existing asset needs augmentation | Asset exists but needs new capabilities for this product |
| New | No existing asset, greenfield decision | No prior work; need full evaluation |
| Replace | Existing asset doesn't fit, needs new solution | Current tool/service is wrong for this product's requirements |
| Build | Create custom solution | Core differentiator, no good alternatives, full control needed |
| Buy | Use paid service or managed product | Commodity capability, proven solutions exist, not a differentiator |
| Integrate | Connect to external platform or API | Ecosystem play, user expects it, data lives elsewhere |
| Research | Need POC before deciding | High uncertainty, multiple viable options, significant commitment |
Evaluation order: Reuse → Vendor-fit → Non-vendor alternatives → Build custom. Default to Buy for everything that isn't a core differentiator.
Decision Framework
| Factor | Favors Reuse/Extend | Favors Buy (Vendor) | Favors Buy (Non-Vendor) | Favors Build |
|---|---|---|---|---|
| Existing asset | Already deployed and working | Vendor has a product | Non-vendor product fits better | Nothing fits |
| Differentiation | Not relevant | Commodity capability | Commodity capability | Core to value prop |
| Vendor alignment | Already committed | Vendor product fits | Vendor has gap or poor fit | No vendor option |
| Compliance | Already compliant | Vendor product is compliant | Non-vendor has compliance cert | Must control compliance |
| Team expertise | Team already operates it | Managed service, less expertise needed | Team knows this tool | Team has deep knowledge |
| Cost | Sunk cost, incremental only | Reasonable vendor pricing | Better price/fit ratio | Long-term cost lower |
Strong Reuse signals:
- "We already run this for [sibling product]"
- "The team already operates and understands this"
- "Switching would cost more than keeping"
Strong Build signals:
- "This is why users choose us over competitors"
- "No existing solution fits our specific need"
- "We need to change this weekly based on learning"
Strong Buy signals:
- "Every product needs this"
- "Multiple proven solutions exist"
- "We'd just be recreating what vendors already built"
Step 1: Discover Existing Assets
Adaptive approach: Check SOT first, then fill gaps with user interview.
If TECH- entries exist in SoT.TECHNICAL_DECISIONS.md:
Read existing entries. Present a summary to the user: "I found these existing technology decisions: [list]. Are these still current? Any changes since these were documented?"
If SOT is empty (first time running this skill): Interview the user with these discovery questions:
-
"Does an existing product family exist with established technology choices?"
- If YES → Load
references/brownfield.mdfor asset discovery workflow - If NO → Proceed to Step 2 with all layers marked as "New"
- If YES → Load
-
"What is the current tech stack?" (ask per area)
- Frontend framework and hosting
- Backend language/framework
- Authentication system
- Database(s)
- Cloud provider and infrastructure
- CI/CD pipeline
- Observability/monitoring tools
-
"Are there vendor constraints (e.g., must use AWS, Azure, or another preferred platform)?"
- If YES → Load the relevant vendor reference if available
- If NO → Proceed with open evaluation
-
"Is this a regulated industry (healthcare, finance, government)?"
- If YES → Note compliance requirements as constraints on all technology choices
Discovery Output
Create a summary table:
| Capability Area | Existing Asset | Status |
|---|---|---|
| [derived from FEA-/RISK-] | [what exists or "None"] | [Reuse / Extend / New / Replace] |
Step 2: Categorize Layers
For each capability required by FEA- and RISK- entries, categorize:
| Category | Criteria | Action |
|---|---|---|
| Reuse | Existing asset covers the need as-is | Create lightweight TECH- entry (use assets/tech-reuse.md) |
| Extend | Existing asset needs augmentation | Create TECH- entry documenting what changes are needed |
| New | No existing asset, greenfield decision | Proceed to Steps 3-4 for full evaluation |
| Replace | Existing asset is wrong for this product | Proceed to Steps 3-4; document what's being replaced and why |
Derive capability areas from upstream IDs, not a fixed list. Read FEA- entries and ask: "What technical capability does this feature require?" Read RISK- entries and ask: "Does this risk constrain or require a specific technology?"
Do not walk a generic layer checklist. Every capability area should trace to at least one FEA- or RISK- entry.
Reference Technology Layers
For context, here are common technology layers in modern products:
| Layer | Questions to Answer | Common Options |
|---|---|---|
| Frontend | Framework? Hosting? Mobile/Web? | React, Vue, Next.js, Vercel |
| Backend | Language? Framework? Serverless? | Node, Python, Go, AWS Lambda |
| Database | SQL/NoSQL? Managed? | PostgreSQL, MongoDB, Supabase |
| Auth | Build or buy? SSO? | Auth0, Clerk, Firebase Auth |
| Payments | If monetized, processor? | Stripe, Paddle, LemonSqueezy |
| Infrastructure | Cloud? Edge? CDN? | AWS, GCP, Vercel, Cloudflare |
| Integrations | External services? APIs? | Depends on product |
| AI/ML | Models? Services? | OpenAI, Anthropic, local models |
| Analytics | Product analytics? Error tracking? | Mixpanel, PostHog, Sentry |
| DevOps | CI/CD? Monitoring? | GitHub Actions, Datadog |
Step 3: Evaluate Vendor Fit
For each "New" or "Replace" layer from Step 2:
- If your team has vendor constraints (AWS-only, Azure-first, etc.), check if the preferred vendor has a product for this capability
- Evaluate fit, compliance status, and cost
- If vendor product fits → create TECH- entry with Category: Buy
- If vendor product has poor fit or gaps → proceed to Step 4
Evaluation criteria for vendor products (or any Buy option):
| Criterion | Questions |
|---|---|
| Fit | Does the vendor product solve our specific need? Feature gaps? |
| Compliance | Does it meet our regulatory requirements (from RISK- entries)? |
| Cost | What's the pricing at your current stage? Can you afford it until you reach product-market fit? (Cost optimization comes later, not MVP.) |
| Maturity | Production-ready? Documentation quality? Active development? |
| Integration | How hard to integrate? Does it work with our existing stack? |
If your team has vendor constraints: Create or load a vendor catalog reference that maps capability areas to vendor products and notes compliance certifications (e.g., HIPAA, SOC2, FedRAMP). Use assets/evaluation-scorecard.md for structured comparison when multiple options exist.
Step 4: Evaluate Alternatives
For layers where vendor options don't exist or have poor fit:
- Research 2-3 non-vendor alternatives
- Score against the same criteria from Step 3
- If a clear winner exists → create TECH- entry with decision
- If high uncertainty → create TECH- entry with Category: Research, including evaluation criteria and deadline
For Research items, define:
- What must be learned before deciding
- How to evaluate (specific metrics, benchmarks, POC scope)
- Decision deadline (tied to a WAVE or milestone)
Use assets/evaluation-scorecard.md for structured scoring when comparing options.
Step 5: Check Product Family
Only if sibling products were discovered in Step 1. Skip for solo/greenfield products.
Lightweight checklist:
- Shared infrastructure? Will this product share clusters, databases, or services with siblings?
- Component reuse? Can UI components, API patterns, or operational tooling be shared?
- Cross-product UX? Should customers using multiple products have SSO or unified experience?
- Shared vs. separate instances? For each reused service, should it be the same deployment (separate namespace/realm) or a dedicated instance?
Document answers in relevant TECH- entries under "Product Family Notes."
Step 6: Create TECH- Entries
For each technology decision, create a TECH- entry using the appropriate template:
- Reuse/Extend: Use
assets/tech-reuse.md(lighter template) - Replace/Build/Buy/Integrate/Research: Use
assets/tech.md(standard template)
Mandatory fields for every TECH- entry:
- Features Served (FEA-XXX references)
- Risk Constraints (RISK-XXX references)
- Rationale (why this choice, not just what)
- Cost (at current AND 10x scale for Buy decisions)
All TECH- entries are written to SoT.TECHNICAL_DECISIONS.md. The skill produces entries; the SoT stores them.
See references/examples.md for 3 filled examples (Reuse, Buy, Research).
Step 7: Map to Risks
Cross-reference every TECH- entry with RISK- constraints:
- For each RISK- entry, verify at least one TECH- entry addresses it
- For each TECH- entry, verify it doesn't introduce new unmitigated risks
- Document the mapping in a summary table:
| Risk | Score | Technology Response |
|---|---|---|
| RISK-XXX | [score] | TECH-XXX addresses this by [how] |
If a RISK- entry has no corresponding TECH- response, flag it as an unmitigated risk requiring attention before proceeding to v0.6.
Quality Gates
Before proceeding to v0.6 Architecture Design:
- All capability areas addressed (or explicitly N/A with rationale)
- Every TECH- entry cross-references FEA- and RISK- IDs it serves
- Build decisions justified as core differentiators
- Buy decisions have realistic cost estimates for your current stage (MVP vs. scaling phase)
- Cost decisions prioritize speed-to-market and quality experience for MVP (not premature optimization)
- Research items have clear evaluation criteria and deadlines
- RISK- constraints from v0.5 Risk Discovery reflected in choices
- No vendor lock-in without explicit acknowledgment
- All TECH- entries written to SoT.TECHNICAL_DECISIONS.md
- Existing assets cataloged before new evaluations (brownfield check)
Anti-Patterns to Avoid
| Pattern | Signal | Fix |
|---|---|---|
| Resume-driven development | "Let's use [hot new tech]" | Choose boring technology for non-differentiators |
| Evaluate everything | Scoring auth when Keycloak already works | Categorize Reuse/Extend/New/Replace first |
| Greenfield assumption | "Pick a frontend framework" when React exists | Discover existing assets before evaluating |
| Build everything | No Buy/Integrate decisions | Challenge: is this really a differentiator? |
| Buy everything | No Build decisions | Some things must be custom for your moat |
| Analysis paralysis | Research everything | Time-box research; decide with 70% confidence |
| Ignoring constraints | Tech choice conflicts with RISK- | Review RISK- entries before finalizing |
| Premature cost optimization | "We must use the cheapest database" for MVP | Optimize for speed-to-market and quality first. Reduce costs after product-market fit. |
| Cost blindness | No cost estimates on Buy decisions | Every TECH- needs realistic cost for your stage |
| Over-engineering for scale | "We need Kubernetes for scale" | Design for 10x current needs, not 1000x unknown scale |
| Orphan TECH- entry | TECH-003 references no FEA- or RISK- | Mandatory cross-reference in template |
| SoT contamination | Decision rationale essays in SoT template | Methodology in skill; structure in SoT |
Bundled Resources
-
references/brownfield.md— Existing product family discovery workflow. Load when user confirms existing products share infrastructure. -
references/examples.md— Completed TECH- entry examples (Reuse, Buy, Research). Load when producing TECH- entries to match format and depth. -
assets/tech.md— Standard TECH- entry template for Replace/Build/Buy/Integrate/Research. -
assets/tech-reuse.md— Lighter TECH- entry template for Reuse/Extend decisions. -
assets/evaluation-scorecard.md— Weighted scorecard for comparing Buy/Integrate options.
Downstream Connections
| Consumer | What It Uses | Example |
|---|---|---|
| v0.6 Architecture Design | TECH- selections define the system | TECH-001 → ARC-001 frontend architecture |
| v0.6 Technical Specification | TECH- informs API design | TECH-003 → API-XXX data model constraints |
| v0.7 Build Execution | TECH- Research items become spikes | TECH-005 (Research) → EPIC task |
| Hiring/Resourcing | TECH- Build items define skills needed | TECH-010 (custom ML) → need ML engineer |
Handoff
TECH- entries are complete when all quality gates pass. Next stage: v0.6 Architecture Design (downstream ownership). The downstream consumer should be able to start architecture work using only TECH- entries + upstream SoT files — no re-research needed.
Architecture Design
Position in workflow: v0.5 Technical Stack Selection → v0.6 Architecture Design → v0.6 Technical Specification
Architecture defines how your system components connect. This skill transforms stack selections into a coherent system design with explicit boundaries and integration patterns.
Consumes
This skill requires prior work from v0.3-v0.5:
- TECH-* technology decisions (from v0.5 Technical Stack Selection) — Tech choices become components; Build items become internal services, Buy/Integrate items become external connections
- RISK-* risk entries (from v0.5 Risk Discovery Interview) — High-priority RISK-* entries must have architectural mitigations; drives design decisions on failover, security, scaling
- FEA-* feature entries (from v0.3 Features Value Planning) — Features determine what components must be built; complex features may require distributed patterns
- ARC-* existing architecture decisions (from prior products if brownfield) — Inherited patterns constrain new designs (monolith with microservice, library reuse, auth pattern, etc.)
This skill assumes v0.5 Technical Stack Selection is complete with TECH- entries providing technology foundations.
Produces
This skill creates/updates:
- ARC-* entries (architecture decisions, status-based) — Decisions for structure, integration, security, performance, data, DevOps with rationale, alternatives considered, and consequences. No confidence scores; decisions have Status: Proposed/Accepted/Superseded
- System boundary diagram — Visual representation showing trust boundaries, components, and external integrations
- RISK-to-Architecture mapping — Validation showing every high-priority RISK-* has corresponding ARC-* mitigation or explicit acceptance
- Conformance rules (on ARC- entries) — for any decision that makes a structural claim ("X must not depend on Y", "all Z go through one adapter"), a machine-checkable rule. This turns the architecture into the expected topology (the blueprint graph) the v0.7 build is diffed against, and feeds the
architecture_conformancereadiness dimension. Seedocs/DEVELOPMENT_GRAPH.md.
All ARC- entries should include:
- Category: Structure/Integration/Security/Performance/Data/DevOps
- Context: What prompted this decision (derived from TECH-/RISK-/FEA- inputs)
- Decision: What was chosen
- Rationale: Why (not just what)
- Alternatives Rejected: Options considered and why not chosen
- Consequences: What this enables and constrains
- Related IDs: TECH-XXX, RISK-XXX, FEA-XXX references
Example ARC- entry (Structure):
ARC-001: Monolith with Module Boundaries
Category: Structure
Context: Team of 2 developers; unclear domain boundaries at v0.6; TECH-001 (Next.js) supports monolith pattern
Decision: Single Next.js application with domain-based module folders (auth/, reports/, data-sources/), clear module interfaces
Rationale:
- TECH-001 (Next.js) designed for monoliths
- Avoids ops complexity of microservices
- Can extract services later when scaling needs emerge
- Enables fast iteration for MVP
Alternatives Rejected:
- Microservices: Premature (team too small); adds ops burden
- Serverless: Harder to share code; cold start latency concerns (impacts UJ-001 response time)
- Layered monolith: Less clear boundaries; module pattern better for future extraction
Consequences:
- Enables: Fast iteration, simple deployment, shared state across domains
- Constrains: Single scaling unit (can't scale auth independently); must be disciplined about module boundaries
Related IDs: TECH-001 (Next.js), RISK-005 (scaling concerns), FEA-001..FEA-020 (all features in one deployment)
Status: Accepted
Example ARC- entry (Security, addressing RISK-):
ARC-005: JWT with HTTP-Only Cookies
Category: Security
Context: Need session management for authenticated users; RISK-008 (security compliance) and TECH-003 (Clerk auth) guide this
Decision: JWTs stored in HTTP-only cookies, 1-hour expiry, refresh via /refresh endpoint
Rationale:
- HTTP-only prevents XSS token theft (mitigates RISK-008 surface area)
- Short expiry limits damage window if token stolen
- Refresh flow handles long sessions gracefully
- TECH-003 (Clerk) handles token lifecycle, we just enforce storage pattern
Alternatives Rejected:
- localStorage: Vulnerable to XSS (RISK-008 violation)
- Long-lived tokens: Increases risk exposure time (RISK-008)
- Server sessions: Scaling complexity; would require Redis (not in TECH-)
Consequences:
- Enables: Stateless auth, horizontal scaling
- Constrains: Must handle refresh flow in frontend; logout requires token invalidation
Related IDs: TECH-003 (Clerk handles token generation), RISK-008 (security compliance), BR-010 (auth requirements)
Status: Accepted
Architecture Decision Categories
| Category | What It Covers | Example Decisions |
|---|---|---|
| Structure | Component organization, boundaries | Monolith vs microservices, module structure |
| Integration | External service connections | API gateway pattern, webhook handlers |
| Security | Auth, authorization, data protection | JWT strategy, role-based access |
| Performance | Scaling, caching, optimization | CDN strategy, database indexing |
| Data | Storage, flow, consistency | Event sourcing, CQRS, replication |
| DevOps | Deployment, monitoring, CI/CD | Container orchestration, observability |
Design Process
- Pull TECH- decisions — What technologies are we building with?
- Pull RISK- constraints — What must the architecture account for?
- Pull FEA- features — What must the system do?
- Define system boundaries — What's in/out of scope?
- Map component relationships — How do parts connect?
- Document integration patterns — How do Buy/Integrate items connect?
- Create ARC- entries — Record decisions with rationale
System Boundary Definition
Before designing components, define what's inside and outside your system:
Inside (Build):
- Core business logic
- Differentiating features
- Custom workflows
Outside (Buy/Integrate):
- Authentication provider
- Payment processor
- Email service
- Analytics
Boundary Questions:
- Where does data enter the system?
- Where does data leave the system?
- What trust boundaries exist?
- What must be fast vs. can be eventual?
Component Relationship Patterns
For Build Components
| Pattern | When to Use | Example |
|---|---|---|
| Monolith | MVP, small team, unclear boundaries | Single Next.js app |
| Modular Monolith | Growing codebase, clear domains | Modules with defined interfaces |
| Microservices | Clear boundaries, scaling needs | Separate auth, billing, core services |
Rule for MVP: Start monolith, extract services when you have evidence of need.
For Buy/Integrate Components
| Pattern | When to Use | Example |
|---|---|---|
| Direct Integration | Simple, trusted service | Call Stripe API directly |
| Adapter Layer | Want to swap providers later | Abstract over auth provider |
| Event Bridge | Async, decoupled | Webhooks → event queue → handlers |
Integration Architecture Patterns
Pattern: Vendor Abstraction
When you Buy a service but want flexibility to switch:
┌─────────────────────────────────────┐
│ Your Application │
├─────────────────────────────────────┤
│ Payment Abstraction Layer │
│ interface PaymentProvider { │
│ charge(amount, token): Result │
│ } │
├─────────────────────────────────────┤
│ StripeAdapter │ PaddleAdapter │
└─────────────────┴───────────────────┘
When to use: High switching cost, multiple viable providers, strategic flexibility needed.
Pattern: Webhook Handler
When integrating with external events:
External Service → Webhook Endpoint → Event Queue → Handler
↓
Signature Verify
↓
Idempotency Check
↓
Enqueue for processing
When to use: External services push events (Stripe, GitHub, etc.).
ARC- Output Template
ARC-XXX: [Decision Title]
Category: [Structure | Integration | Security | Performance | Data | DevOps]
Context: [What prompted this decision]
Decision: [What we decided]
Rationale: [Why this choice]
Alternatives Rejected:
- [Option A]: [Why not]
- [Option B]: [Why not]
Consequences:
- Enables: [What this makes possible]
- Constrains: [What this limits]
Conformance Rule (optional — for structural claims):
- Rule: [e.g. "engine/ must not import the UI framework"]
- Check: [type · scope · target, e.g. forbidden_import · engine/** · vscode]
(verified against the as-built code in v0.7 → architecture_conformance; see docs/DEVELOPMENT_GRAPH.md)
Related IDs: [TECH-XXX, RISK-XXX, FEA-XXX]
Status: [Proposed | Accepted | Superseded]
Example ARC- entry:
ARC-001: Monolith with Module Boundaries
Category: Structure
Context: Need to choose application structure for MVP launch
Decision: Single Next.js application with domain-based module folders
Rationale:
- Team of 2 developers, single deployment simplifies ops
- Unclear domain boundaries at this stage
- Can extract services later when patterns emerge
Alternatives Rejected:
- Microservices: Premature; adds ops complexity without proven need
- Serverless functions: Harder to share code, cold start concerns
Consequences:
- Enables: Fast iteration, simple deployment, shared state
- Constrains: Single scaling unit, must be disciplined about module boundaries
Related IDs: TECH-001 (Next.js), RISK-005 (scaling concerns)
Status: Accepted
Example ARC- entry (Security):
ARC-005: JWT with HTTP-Only Cookies
Category: Security
Context: Need session management strategy for authenticated users
Decision: JWTs stored in HTTP-only cookies, 1-hour expiry, refresh via /refresh endpoint
Rationale:
- HTTP-only prevents XSS access to tokens
- Short expiry limits damage from stolen tokens
- Refresh flow handles long sessions gracefully
Alternatives Rejected:
- localStorage: Vulnerable to XSS
- Long-lived tokens: Security risk if compromised
- Server-side sessions: Scaling complexity, Redis dependency
Consequences:
- Enables: Stateless auth, horizontal scaling
- Constrains: Must handle refresh flow in frontend, logout requires invalidation strategy
Related IDs: TECH-001 (Clerk handles this), RISK-008 (security compliance)
Status: Accepted
System Diagram Elements
When creating architecture diagrams, include:
| Element | Symbol | Purpose |
|---|---|---|
| Service/Component | Box | Internal services, modules |
| External System | Cloud/cylinder | Third-party services, DBs |
| Trust Boundary | Dashed line | Security perimeters |
| Data Flow | Arrow | How data moves |
| Integration Point | Diamond | Where systems connect |
Example Diagram Structure
┌─────────────────────────────────────────────────────────┐
│ TRUST BOUNDARY │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Frontend │────▶│ API │───▶│ Database │ │
│ │ (Next.js) │ │ (tRPC) │ │ (Supabase)│ │
│ └─────────────┘ └──────┬──────┘ └────────────┘ │
│ │ │
└─────────────────────────────┼────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Stripe │ │ Clerk │ │ Resend │
│ (payments)│ │ (auth) │ │ (email) │
└──────────┘ └──────────┘ └──────────┘
EXTERNAL SERVICES
RISK- to Architecture Mapping
Every high-priority risk should have an architectural response:
| Risk | Architecture Response |
|---|---|
| RISK-001: API dependency outage | ARC-010: Add retry + circuit breaker |
| RISK-003: Data breach | ARC-005: Encryption at rest + transit |
| RISK-007: Scaling bottleneck | ARC-012: Cache layer, read replicas |
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Architecture astronaut | Over-engineering for 1000x scale | Design for 10x current needs |
| Missing boundaries | Everything can call everything | Define clear interfaces |
| Ignoring RISK- | Architecture doesn't address risks | Map each High RISK- to ARC- |
| Vendor lock-in | No abstraction over critical services | Add adapter layer for switching |
| Diagram without decisions | Pretty pictures, no ARC- records | Every box needs documented rationale |
| Premature microservices | 5 services for MVP | Start monolith, extract later |
Quality Gates
Before proceeding to Technical Specification:
- All TECH- Build items have component placement
- All TECH- Buy/Integrate items have integration pattern
- High-priority RISK- entries have architectural mitigation
- Trust boundaries clearly defined
- Data flow documented
- ARC- entries created for major decisions
Downstream Connections
ARC- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| Technical Specification | ARC- informs API design | ARC-001 (monolith) → unified API surface |
| v0.7 Build Execution | ARC- defines EPIC scope | ARC-003 (auth module) → EPIC-02 |
| Development Graph (v0.7) | ARC- conformance rules become code checks | ARC-004 (no UI import in engine/) → architecture_conformance verdict |
| Infrastructure Setup | ARC- drives deployment | ARC-010 (edge caching) → CDN config |
| Security Review | Security ARC- entries | ARC-005 → pen test scope |
Detailed References
- Architecture pattern examples: See
references/examples.md - ARC- entry template: See
assets/arc.md - Diagram templates: See
references/diagrams.md
Environment Setup
Position in workflow: v0.6 Architecture Design / Technical Specification → v0.6 Environment Setup → v0.7 Build Execution
Environment setup documents the tools, packages, and configurations developers need to work on the project. This eliminates environment drift and speeds up onboarding.
Consumes
This skill requires prior work from v0.5-v0.6:
- TECH-* technology decisions (from v0.5 Technical Stack Selection) — Choices for frontend/backend/database/CI/CD determine which tools, languages, and package managers developers need
- ARC-* architecture decisions (from v0.6 Architecture Design) — Architectural patterns (monolith vs microservices, container strategy, deployment topology) inform infrastructure and scripting needs
This skill assumes v0.5 Technical Stack Selection is complete with TECH- entries specifying the tech stack.
Produces
This skill creates/updates:
- ENV-001: Development Environment — Local setup specification with CLIs (global), packages (per-project), config files, verification steps. Enables consistent development experience across team
- ENV-002: CI/CD Pipeline (optional) — Automated testing and deployment workflow specifications with required secrets and pipeline stages
- ENV-003: Production Infrastructure (optional) — Production hosting, environment variables, services, and deployment topology
All ENV- entries are specifications, not confidence-based. They are:
- Concrete and verifiable (each CLI/package has an install command; each config file has a purpose)
- Preferring CLIs over MCPs (standard tools work in CI/CD; MCPs don't scale)
- Per-project, not global (package managers install dependencies in the project, not globally)
Example ENV-001 entry (Development Environment):
ENV-001: Development Environment
Category: Development Setup
Status: Approved | Date: 2026-02-26
Owner: Engineering Team
Purpose:
Local development setup for team consistency and AI agent understanding.
CLIs (Global, install once):
- Node.js 20.x: https://nodejs.org — Language runtime
Install: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash && nvm install 20`
Verify: `node --version`
- mise: https://mise.jdx.dev — Version manager
Install: `curl https://mise.jdx.dev/install.sh | sh`
Verify: `mise --version`
Packages (Per-Project):
- typescript: Type checking (devDependency)
- eslint, prettier: Code quality (devDependencies)
- jest: Testing framework (devDependency)
- Listed in package.json, installed via: `npm install`
Configuration Files:
| File | Purpose |
|------|---------|
| package.json | Dependencies, scripts, project metadata |
| tsconfig.json | TypeScript compiler options |
| .eslintrc.json | Linting rules |
| .prettierrc | Code formatting rules |
| .env.example | Template for environment variables |
Scripts:
{
"validate": "npm run lint && npm run type-check",
"lint": "eslint src/",
"fix": "eslint src/ --fix && prettier --write src/",
"type-check": "tsc --noEmit",
"test": "jest",
"dev": "next dev",
"build": "next build"
}
Verification:
# 1. Check global CLIs
node --version
mise --version
# 2. Check per-project packages
npm list | head -20
# 3. Run validation
npm run validate
# 4. Run tests
npm run test
Related IDs: TECH-001 (Next.js), TECH-002 (TypeScript), ARC-001 (monolith structure)
Example ENV-002 entry (CI/CD):
ENV-002: CI/CD Pipeline
Category: Automation
Status: Approved | Date: 2026-02-26
Purpose:
Automated testing and deployment configuration.
Workflow Files:
- .github/workflows/test.yml: Run tests on push to any branch
- .github/workflows/deploy.yml: Deploy main branch to production on merge
Required Secrets (set in GitHub Settings → Secrets):
| Secret | Purpose |
|--------|---------|
| VERCEL_TOKEN | Authentication for Vercel deployment |
| DATABASE_URL | Production database connection string |
| API_KEY | Third-party API credentials |
Pipeline Stages:
1. Install: `npm install`
2. Lint: `npm run validate` (must pass)
3. Test: `npm run test` (must pass)
4. Build: `npm run build` (must succeed)
5. Deploy: Push to Vercel (main branch only)
Related IDs: ENV-001, TECH-002 (Node.js), ARC-001 (monolith deployment)
Environment Types
| Type | What It Defines | When Required |
|---|---|---|
| ENV-001 | Development environment (local setup) | Always |
| ENV-002 | CI/CD pipeline configuration | When using automated testing/deployment |
| ENV-003 | Production infrastructure | When deploying to production |
Rule: ENV-001 (Development Environment) is required for every project. ENV-002 and ENV-003 are optional based on project needs.
Design Principles
1. Prefer CLIs Over MCPs
Rule: Use CLIs for operations, MCPs only when CLIs are insufficient.
| Factor | CLI | MCP |
|---|---|---|
| Works in CI/CD | Yes | No |
| Works locally | Yes | Yes (limited contexts) |
| Structured output | JSON, exit codes | Varies |
| Debugging | Standard tools | Harder |
Decision: Default to CLI. Only document MCPs for operations where CLIs don't exist.
2. Per-Project Over Global
Rule: Language-specific packages installed per-project, not globally.
Global (OK):
- Version managers (mise, asdf, nvm)
- System tools (jq, ripgrep)
- Platform CLIs (gh, aws-cli)
Per-Project (Required):
- Linters/formatters (eslint, prettier)
- Type checkers (typescript)
- Testing frameworks (jest, pytest)
3. Structured Over Prose
Rule: ENV- specs use structured data (tables, code blocks), not narrative.
Why:
- AI agents can parse and execute
- Humans can scan quickly
- Diff-friendly in version control
4. Verification Required
Rule: Every ENV- spec includes verification commands.
Why:
- Confirms setup succeeded
- Debugging aid
- Onboarding confidence
Setup Process
- Pull TECH- decisions — What technologies are we using?
- Pull ARC- decisions — What architecture patterns apply?
- Inventory tooling needs — What do developers need installed?
- Categorize by scope — Global vs per-project
- Define configuration files — What configs are needed?
- Create verification steps — How to confirm setup works?
- Document in ENV- entries — Record in SoT.TECHNICAL_DECISIONS.md
ENV-001 Output Template (Development Environment)
ENV-001: Development Environment
Category: Development Setup
Status: Approved | Date: YYYY-MM-DD
Owner: {Team/Person}
Purpose:
Document local development requirements for team consistency.
CLIs (Global):
- {tool}: {purpose} — {install command}
Packages (Per-Project):
- {package}: {purpose}
Configuration Files:
| File | Purpose |
|------|---------|
| {file} | {purpose} |
Scripts:
{
"validate": "{quality check command}",
"fix": "{auto-fix command}",
"test": "{test command}"
}
Verification:
# 1. Check tools
{tool} --version
# 2. Check packages
{package manager list command}
# 3. Run validation
npm run validate
Related IDs: TECH-XXX, ARC-XXX
ENV-002 Output Template (CI/CD Pipeline)
ENV-002: CI/CD Pipeline
Category: Automation
Status: Approved | Date: YYYY-MM-DD
Purpose:
Document automated testing and deployment configuration.
Workflow Files:
- {path}: {purpose}
Required Secrets:
| Secret | Purpose | Where to Set |
|--------|---------|--------------|
| {name} | {purpose} | {location} |
Pipeline Stages:
1. {Stage}: {What happens}
2. {Stage}: {What happens}
Related IDs: ENV-001, DEP-XXX
ENV-003 Output Template (Production Infrastructure)
ENV-003: Production Infrastructure
Category: Infrastructure
Status: Approved | Date: YYYY-MM-DD
Purpose:
Document production hosting and services configuration.
Hosting Platform:
{Platform and configuration details}
Environment Variables:
| Variable | Purpose | Required |
|----------|---------|----------|
| {name} | {purpose} | {yes/no} |
Services:
| Service | Purpose | Connection |
|---------|---------|------------|
| {service} | {purpose} | {how connected} |
Related IDs: DEP-XXX, MON-XXX
Common Tool Categories
Version/Environment Managers
mise,asdf,nvm,pyenv,rbenv- Purpose: Manage language versions per-project
Code Quality
- JavaScript/TypeScript:
eslint,prettier,biome - Python:
ruff,black,pylint - Go:
golangci-lint
Type Checking
- JavaScript/TypeScript:
typescript - Python:
mypy,pyright
Data Processing
jq(JSON),yq(YAML)
API Testing
httpie,curl,bruno-cli
Git Workflows
gh(GitHub CLI),glab(GitLab CLI)
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Global package pollution | npm install -g for project packages | Use devDependencies |
| Missing verification | No way to confirm setup | Add verification commands |
| Prose instead of structure | Long paragraphs describing setup | Use tables and code blocks |
| MCP over CLI | Using MCP when CLI exists | Prefer CLI for portability |
| Undocumented config | Config files without explanation | Document purpose of each file |
| Implicit dependencies | Setup fails without warning | List all dependencies explicitly |
Quality Gates
Before proceeding to Build Execution:
- ENV-001 documents all development tools
- All tools have install commands
- All packages are in package manifest
- Configuration files are listed with purpose
- Standard scripts defined (validate, fix, test)
- Verification commands work
- CLI preferred over MCP documented
Downstream Connections
ENV- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.7 Build Execution | ENV-001 defines dev setup | Developer follows ENV-001 to set up |
| Onboarding | ENV-001 as setup guide | New dev uses ENV-001 for first day |
| CI/CD | ENV-002 defines pipeline | GitHub Actions mirrors ENV-002 |
| Deployment | ENV-003 defines infrastructure | DEP- references ENV-003 |
Detailed References
- ENV- entry template: See
assets/env.md - Environment examples: See
references/examples.md
Technical Specification
Position in workflow: v0.6 Architecture Design → v0.6 Technical Specification → v0.7 Build Execution
Technical specification defines the contracts developers build against: API endpoints and data models. This is the bridge between architecture and implementation.
Consumes
This skill requires prior work from v0.3-v0.6:
- ARC-* architecture decisions (from v0.6 Architecture Design) — System structure (monolith vs microservices) determines API organization; integration patterns guide webhook/adapter design
- TECH-* Build items (from v0.5 Technical Stack Selection) — Technologies chosen define data model types (PostgreSQL requires relational schema; MongoDB requires document schema)
- UJ-* user journeys (from v0.4 User Journey Mapping) — Journey steps determine API call sequences; value moments determine response contracts
- SCR-* screen entries (from v0.4 Screen Flow Definition) — Screen data requirements determine API response shape; form submissions map to POST/PUT/PATCH endpoints
- BR-* business rules (from v0.3 Commercial Model) — Business constraints enforced in API responses (rate limits, validation rules, field constraints)
This skill assumes v0.6 Architecture Design is complete with ARC- entries providing system structure.
Produces
This skill creates/updates:
- API-* entries (API endpoint contracts) — REST/GraphQL endpoint specifications with request/response shapes, auth requirements, error codes, tied to UJ-/SCR- consumers and DBT- data sources
- DBT-* entries (database schema contracts) — Data model specifications with fields, relationships, indexes, constraints, tied to API- accessors and BR- rules
- Screen-to-API validation matrix — Verification showing every SCR-* has supporting API-* and every UJ-* step can be completed via API calls
- API-to-Data validation matrix — Verification showing every API-* response field maps to DBT-* and every DBT-* is used by at least one API-*
All API- and DBT- entries are implementation contracts (not confidence-based). They are:
- Derivable from upstream IDs (UJ-/SCR-/ARC-/BR-/TECH-)
- Testable (API responses have concrete shape, DBT constraints are verifiable)
- Complete enough for developers to implement without re-research
Example API- entry (from UJ- and SCR-):
API-001: Create Report
Method: POST
Path: /api/reports
Purpose: Create new report from selected data source and template (implements UJ-001 Step 1)
Auth: User
Journey: UJ-001 (Step 1 - Create Report)
Screen: SCR-002 (Report Builder)
Request:
Body:
{
title: string (required) — Report name
templateId: string (required) — Selected template (FEA-008)
dataSourceId: string (required) — Connected data source (FEA-001)
options: { dateRange: { start, end }, filters: [...] }
}
Response:
Success (201):
{
data: { id, title, status: "pending|generating|ready", createdAt }
}
Errors:
- 400: Invalid input — Missing required field
- 403: Forbidden — User doesn't own data source
- 404: Not found — Template or data source not found
- 429: Rate limit exceeded
Business Rules: BR-015 (max 100 reports per user)
Data: DBT-001 (reports table), DBT-002 (data_sources table)
Example DBT- entry (referenced by API- entries):
DBT-001: Reports
Purpose: Stores user-generated reports (entities created by API-001, updated by API-004)
Table: reports
Fields:
- id: uuid — Primary key
- user_id: uuid — Report owner (FK → users) [NOT NULL]
- title: varchar(255) — Display name [NOT NULL]
- status: enum('pending','generating','ready','failed') [NOT NULL]
- created_at: timestamp [NOT NULL, DEFAULT now()]
Relationships:
- belongs_to: users via user_id
- belongs_to: templates via template_id
Indexes:
- user_id — List reports by user (API-003)
- (user_id, created_at DESC) — Recent reports (API-003)
- status — Find pending reports (background job)
Constraints:
- title: NOT NULL, length 1-255
- status: valid enum only
Business Rules: BR-015 (max 100 per user — enforce in API-001)
APIs: API-001 (create), API-002 (get), API-003 (list), API-005 (delete)
Specification Types
| Type | What It Defines | Example |
|---|---|---|
| API- | Endpoint contracts | POST /users, GET /reports/:id |
| DBT- | Data model/schema | Users table, Reports table |
Rule: Every API- should know which DBT- it reads/writes. Every DBT- should know which API- accesses it.
Specification Process
-
Pull ARC- decisions — System structure and boundaries
-
Pull TECH- Build items — What we're implementing
-
Pull UJ- journeys — User flows the API must support
-
Pull SCR- screens — UI data requirements
-
Define API contracts for each endpoint:
- What's the request/response shape?
- What auth is required?
- What errors can occur?
-
Define data models for each entity:
- What fields exist?
- What relationships?
- What constraints?
-
Validate consistency:
- Does every screen have APIs to fetch its data?
- Does every API response map to DBT- fields?
API- Output Template
API-XXX: [Endpoint Name]
Method: [GET | POST | PUT | PATCH | DELETE]
Path: [/resource/{id}/action]
Purpose: [What this endpoint does]
Auth: [Public | User | Admin | Service]
Journey: [UJ-XXX that uses this]
Screen: [SCR-XXX that calls this]
Request:
Headers:
- Authorization: Bearer <token>
- Content-Type: application/json
Params:
- id: string (required) — Resource identifier
Query:
- limit: number (optional, default 20) — Pagination limit
Body:
{
field: type — Description
}
Response:
Success (200/201):
{
data: { ... }
}
Errors:
- 400: Invalid input — [when this occurs]
- 401: Unauthorized — [when this occurs]
- 404: Not found — [when this occurs]
- 500: Server error — [when this occurs]
Business Rules: [BR-XXX enforced here]
Data: [DBT-XXX entities accessed]
Rate Limit: [requests/minute if applicable]
Example API- entry:
API-001: Create Report
Method: POST
Path: /api/reports
Purpose: Create a new report from selected data source and template
Auth: User
Journey: UJ-001 (Step 1 - Create Report)
Screen: SCR-002 (Report Builder)
Request:
Headers:
- Authorization: Bearer <token>
- Content-Type: application/json
Body:
{
title: string (required) — Report name
templateId: string (required) — Selected template
dataSourceId: string (required) — Connected data source
options: {
dateRange: { start: ISO8601, end: ISO8601 }
filters: [{ field: string, operator: string, value: any }]
}
}
Response:
Success (201):
{
data: {
id: string
title: string
status: "pending" | "generating" | "ready"
createdAt: ISO8601
}
}
Errors:
- 400: Invalid input — Missing required field or invalid templateId
- 401: Unauthorized — Invalid or expired token
- 403: Forbidden — User doesn't own data source
- 404: Not found — Template or data source not found
- 429: Too many requests — Rate limit exceeded
Business Rules: BR-015 (max 100 reports per user)
Data: DBT-001 (reports), DBT-002 (data_sources)
Rate Limit: 10 requests/minute
DBT- Output Template
DBT-XXX: [Entity Name]
Purpose: [What this entity represents]
Table: [database_table_name]
Fields:
- id: uuid — Primary key, auto-generated
- [field_name]: [type] — Description [constraints]
- created_at: timestamp — Record creation (auto)
- updated_at: timestamp — Last modification (auto)
Relationships:
- belongs_to: [DBT-YYY] via [foreign_key]
- has_many: [DBT-ZZZ]
Indexes:
- [field_name] — [Query pattern it supports]
Constraints:
- [field]: [UNIQUE | NOT NULL | CHECK expression]
Business Rules: [BR-XXX that affect this entity]
APIs: [API-XXX that read/write this]
Example DBT- entry:
DBT-001: Reports
Purpose: Stores user-generated reports with configuration and status
Table: reports
Fields:
- id: uuid — Primary key
- user_id: uuid — Report owner (FK → users) [NOT NULL]
- title: varchar(255) — Display name [NOT NULL]
- template_id: uuid — Template used (FK → templates) [NOT NULL]
- data_source_id: uuid — Data source (FK → data_sources) [NOT NULL]
- status: enum('pending','generating','ready','failed') — Generation status [NOT NULL, DEFAULT 'pending']
- options: jsonb — Report configuration (date range, filters) [DEFAULT '{}']
- output_url: varchar(500) — Generated report file URL [NULL until ready]
- created_at: timestamp — [NOT NULL, DEFAULT now()]
- updated_at: timestamp — [NOT NULL, DEFAULT now()]
Relationships:
- belongs_to: DBT-010 (users) via user_id
- belongs_to: DBT-002 (templates) via template_id
- belongs_to: DBT-003 (data_sources) via data_source_id
Indexes:
- user_id — List reports by user
- (user_id, created_at DESC) — List recent reports
- status — Find pending reports for processing
Constraints:
- title: NOT NULL, length 1-255
- status: NOT NULL, valid enum value
Business Rules: BR-015 (max 100 reports per user — enforce in API)
APIs: API-001 (create), API-002 (get), API-003 (list), API-005 (delete)
API Design Principles
| Principle | Guidance | Example |
|---|---|---|
| Resource-oriented | URLs are nouns, not verbs | /reports not /createReport |
| Consistent naming | Plural nouns, kebab-case | /data-sources not /dataSource |
| Stateless | No server-side sessions | Auth via token, not cookie session |
| Versioned | Prefix for breaking changes | /v1/reports |
| Documented errors | Clear codes and messages | { error: { code: "LIMIT_EXCEEDED", message: "..." } } |
Data Model Principles
| Principle | Guidance | Example |
|---|---|---|
| Normalized | Avoid redundancy (unless denormalized for performance) | User name in users table, not duplicated |
| Audit trail | created_at, updated_at on all tables | Track when records change |
| Soft delete | deleted_at instead of hard delete (when needed) | Recover deleted data |
| Foreign keys | Enforce referential integrity | user_id → users.id |
| Index strategy | Index fields in WHERE and JOIN | Filter fields, FK columns |
Validation Checklist
Use this to ensure spec completeness:
Screen-to-API Validation
- Every SCR- screen has APIs to fetch its data
- Every form submission maps to a POST/PUT/PATCH
- Every list view has a paginated GET
Journey-to-API Validation
- Every UJ- step that needs data has an API call
- API sequence supports journey flow
- Error states in journey have error responses
API-to-Data Validation
- Every API- response field maps to DBT- fields
- Every API- that writes data has a target DBT-
- Business rules (BR-) enforced in API or DB constraint
Orphan Check
- No API- without SCR-/UJ- consumer
- No DBT- table unused by any API-
- No dead code paths
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| API/UI mismatch | Screen needs data not in any API | Add API- or modify existing |
| Schema sprawl | 50+ tables for MVP | Consolidate; YAGNI applies |
| Missing constraints | No validation, anything accepted | Add BR- enforcement |
| N+1 queries baked in | API design requires multiple calls for one view | Add compound endpoints |
| No error handling | Only happy path documented | Define all error responses |
| Vague types | data: any | Specify exact shape |
Quality Gates
Before proceeding to Build Execution:
- All SCR- screens have supporting API- endpoints
- All UJ- journeys can be completed via API- calls
- All API- responses map to DBT- fields
- All BR- rules enforced in API- or DBT- constraints
- No orphaned tables or endpoints
- Error responses documented for all endpoints
Downstream Connections
API- and DBT- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.7 Epic Scoping | API- and DBT- define EPIC scope | EPIC-01 implements API-001–005 |
| v0.7 Test Planning | API- defines test contracts | TEST-001 validates API-001 |
| v0.7 Implementation Loop | API-/DBT- are implementation tasks | Code implements API-001 |
| API Documentation | API- becomes OpenAPI spec | Swagger from API- entries |
Detailed References
- API and data model examples: See
references/examples.md - API- entry template: See
assets/api.md - DBT- entry template: See
assets/dbt.md
Epic Scoping
Position in workflow: v0.6 Technical Specification → v0.7 Epic Scoping → v0.7 Test Planning
Consumes
This skill requires prior work from v0.6 Technical Specification:
- API-* endpoint contracts (from v0.6 Technical Specification) — Endpoints define what must be built; API count signals complexity
- DBT-* data model specifications (from v0.6 Technical Specification) — Data entities and relationships inform natural boundaries
- ARC-* architecture decisions (from v0.6 Architecture Design) — System structure, module boundaries, and integration patterns define scoping boundaries
- FEA-* feature entries with MVP-SCOPE (from v0.3 Features Value Planning) — MVP boundary determines EPIC scope; post-MVP features defer to backlog
- Existing EPIC-* entries (if brownfield) — Inherited work packages constrain and sequence new EPICs
This skill assumes v0.6 Technical Specification is complete with API-/DBT- entries providing implementation contracts.
Produces
This skill creates/updates:
- EPIC-* entries (context-window-sized work packages, status-based) — Scope of work that fits in AI agent working memory with explicit dependencies, pre-load context budget, session state tracking, and acceptance criteria
- EPIC dependency graph — Sequencing showing which EPICs must complete before others; identifies infrastructure/foundation EPICs, critical path EPICs, and optional/secondary EPICs
- Context capsule specification — Pre-load checklist (SoT files, key IDs, code references) and working room estimate ensuring EPIC doesn't exceed 100k context tokens
All EPIC- entries are work package specifications, not confidence-based. They are:
- Sized for context windows (3-5 APIs, 2-4 DBT tables, 1-2 UJs, <100k pre-load tokens)
- Fully traceable (every EPIC references API-, DBT-, BR-, UJ-, TEST- from upstream)
- Sequenced explicitly (dependencies form a DAG; no circular dependencies)
- Deliverable-focused (measurable completion with acceptance criteria)
Example EPIC- entry (Auth Infrastructure):
EPIC-01: User Authentication
State: Planned
Lifecycle: v0.7 Build Execution
Branch: epic/EPIC-01-auth
## 0. Context Capsule
### Resource Envelope
| Dimension | Target | Notes |
|-----------|--------|-------|
| Pre-load Context | ~40k tokens | Auth SoT + API-001–005 specs + DBT-010/011 schema |
| Working Room | ~160k tokens | Plenty of space for implementation |
| Session Goal | Checkpoint C1 | Database schema complete |
### Dependencies
| Type | Items | Status |
|------|-------|--------|
| Requires | None | First EPIC — foundation |
| External | Supabase project created | Ready |
| Enables | EPIC-02 (reports), EPIC-03 (data sources) | Blocked until auth completes |
### Pre-load Checklist
- [ ] SoT/SoT.BUSINESS_RULES.md — IDs: BR-001, BR-002 (auth rules)
- [ ] SoT/SoT.API_CONTRACTS.md — IDs: API-001–005 (auth endpoints)
- [ ] SoT/SoT.TECHNICAL_DECISIONS.md — IDs: TECH-003 (Clerk), ARC-003 (JWT strategy)
## 2. Objective & Scope
Goal: Enable users to authenticate with email/password, manage sessions, and maintain security.
Deliverables:
- [ ] User registration with email/password (API-001)
- [ ] Login/logout functionality (API-002, API-003)
- [ ] Session management with refresh tokens (API-004)
- [ ] Password reset flow (API-005)
- [ ] Users and sessions schema (DBT-010, DBT-011)
Out of Scope: Social auth (EPIC-02), team invites (EPIC-05), admin user management (EPIC-07)
## 3. Context & IDs
| Type | IDs |
|------|-----|
| Business Rules | BR-001 (email uniqueness), BR-002 (password requirements), BR-010 (auth workflow) |
| User Journeys | UJ-000 (onboarding), UJ-010 (login) |
| APIs | API-001 to API-005 |
| Data Models | DBT-010 (users), DBT-011 (sessions) |
| Architecture | ARC-003 (JWT strategy), TECH-003 (Clerk) |
| Features | FEA-010 (signup), FEA-011 (login) — both in MVP-SCOPE |
| Tests | TEST-001 to TEST-015 (auth test suite) |
## 4. Execution Plan (5 Phases)
[Phase structure from skill as is]
Related IDs: TECH-003, ARC-003, FEA-010/011, API-001–005, DBT-010/011, BR-001/002/010
Core Concept: Epic = Context Window
An EPIC is not a "big user story." It is a cognitive boundary—a scope of work that fits in working memory (human or AI). The goal is to load exactly what's needed to complete a focused task without distraction.
The question is not "How long will this take?" but "Can an agent complete this without needing more context than fits in a session?"
Sizing Rules
| Size | Characteristics | Action |
|---|---|---|
| Right-sized | 3-5 API endpoints, 2-4 DBT tables, 1-2 UJ flows | Good fit ✓ |
| Too big | >10 APIs, >5 tables, multiple unrelated features | Split by domain |
| Too small | Single endpoint, no meaningful deliverable | Merge with related |
Rule of thumb: If you can't describe the EPIC's goal in one sentence, it's too big.
Context Budget Guidelines
EPICs are context capsules — work units sized for AI agent handoffs.
| Dimension | Target | Rationale |
|---|---|---|
| Pre-load context | <100k tokens | SoT files + EPIC + code references |
| Working room | >100k tokens | Space for tool outputs, debugging, iteration |
| Session goal | 1 checkpoint | Clear "done" state per session |
Context Monitoring: Don't estimate upfront — monitor during work. If context exceeds 100k tokens mid-session, pause and checkpoint immediately.
Splitting Signal: If you need to load >5 SoT files or >10 code files to understand the EPIC, it's probably too big.
Simplicity Signal: Resist creating more EPICs "just in case." Each EPIC adds coordination overhead (context capsule, session state, branch management, dependency tracking). If the MVP has 12 APIs and 6 tables, 3-5 EPICs is almost always sufficient. The overhead of an unnecessary EPIC is higher than a slightly larger EPIC that stays within context budget.
Branch Convention
Each EPIC gets its own branch. This creates:
- Clear ownership (one EPIC = one branch = one PR)
- Easy rollback (delete branch, EPIC never happened)
- Natural checkpoint = commit
Naming: epic/EPIC-{NUMBER}-{slug}
Examples:
epic/EPIC-01-auth-endpointsepic/EPIC-02-user-dashboardepic/EPIC-03-payment-integration
Workflow:
- EPIC created →
git checkout -b epic/EPIC-{NUMBER}-{slug} - Work happens → Commits reference IDs in messages
- Checkpoints → Commit with state saved in EPIC Section 1
- EPIC complete → PR opened
- PR merged → Branch deleted, EPIC marked Complete
Scoping Process
-
Inventory implementation items from API-, DBT-, FEA-, ARC-
- What must be built?
-
Identify natural boundaries
- Feature clusters (features that work together)
- Data domains (tables that belong together)
- Architectural seams (module boundaries from ARC-)
- Surface ambiguous assignments: When an API/DBT could logically belong to either EPIC, state the ambiguity explicitly: "API-012 could belong to EPIC-02 or EPIC-03 because it serves both UJ-005 and UJ-008." Record the reasoning for the final placement in the EPIC's Context & IDs section. Do not silently assign items to whichever EPIC you encounter first.
-
Size each potential EPIC against context window capacity
- Can an agent hold all relevant IDs in one session?
-
Sequence EPICs by dependencies
- What must be built first?
- What enables other EPICs?
-
Create EPIC- entries with full ID references
-
Validate: Can an agent complete this EPIC without needing more context than fits in a session?
Sequencing Framework
| Order | Priority | Rationale | Examples |
|---|---|---|---|
| 1 | Infrastructure EPICs | Everything depends on these | Auth, DB setup, project scaffold |
| 2 | Core data model EPICs | Foundation for features | User, Workspace, base entities |
| 3 | Critical path EPICs | Journeys that drive KPIs | UJ- that affects KPI-001 |
| 4 | Supporting feature EPICs | Secondary features | Settings, admin, nice-to-haves |
EPIC- Output Template
EPIC-XXX: [Epic Name]
State: [Planned | In Progress | Testing | Complete]
Lifecycle: v0.7 Build Execution
Branch: epic/EPIC-XXX-[slug]
## 0. Context Capsule
### Resource Envelope
| Dimension | Target | Notes |
|-----------|--------|-------|
| Pre-load Context | ~[N]k tokens | SoT files + EPIC + code |
| Working Room | ~[200-N]k tokens | Space for work |
| Session Goal | [Checkpoint target] | What "done" looks like |
### Dependencies
| Type | Items | Status |
|------|-------|--------|
| Requires | EPIC-YYY | Complete/Pending |
| External | [Setup needed] | Ready/Blocked |
| Enables | EPIC-ZZZ | Blocked until this completes |
### Pre-load Checklist
- [ ] SoT/SoT.[X].md — IDs: [key IDs]
- [ ] SoT/SoT.[Y].md — IDs: [key IDs]
## 1. Session State (The "Brain Dump")
### Current State
- **Last Action**: [What was just completed — reference IDs]
- **Stopping Point**: [File/line or test failure]
- **Next Steps**: [Exact instructions for next session]
- **Blockers**: [Any blockers — or "None"]
- **Decisions Made**: [Key decisions with rationale]
### Resume Instructions
[Exactly what the next session should do — or "N/A - EPIC Complete"]
## 2. Objective & Scope
Goal: [One sentence describing what this EPIC achieves]
Deliverables:
- [ ] [Specific deliverable A]
- [ ] [Specific deliverable B]
- [ ] [Specific deliverable C]
Out of Scope: [What we are NOT doing in this EPIC]
## 3. Context & IDs
| Type | IDs |
|------|-----|
| Business Rules | BR-XXX, BR-YYY |
| User Journeys | UJ-XXX, UJ-YYY |
| APIs | API-XXX to API-ZZZ |
| Data Models | DBT-XXX, DBT-YYY |
| Architecture | ARC-XXX |
| Features | FEA-XXX, FEA-YYY |
| Tests | TEST-XXX to TEST-ZZZ |
## 4. Execution Plan (The 5 Phases)
### Phase A: Plan
- [ ] Context loaded
- [ ] Dependencies verified
- [ ] Strategy defined
- [ ] Branch created
**Checkpoint A**: Planning complete, branch exists.
### Phase B: Design
- [ ] Specs updated
- [ ] Architecture documented
- [ ] TEST- entries created
**Checkpoint B**: Specs drafted, tests defined.
### Phase C: Build (Context Windows)
Window 1: [Focus Area]
- [ ] Task A
- [ ] Task B
- [ ] Verification: [How to confirm complete]
**Checkpoint C1**: [What exists when done]
Window 2: [Focus Area]
- [ ] Task C
- [ ] Task D
**Checkpoint C2**: [What exists when done]
### Phase D: Validate
- [ ] All TEST- entries pass
- [ ] Manual verification of UJ-
- [ ] Code has @implements tags
- [ ] SoT matches implementation
**Checkpoint D**: Tests green, verification complete.
### Phase E: Finish
- [ ] Temp cleanup
- [ ] SoT finalized
- [ ] Learning capture
- [ ] Resume Instructions = "N/A - EPIC Complete"
- [ ] PR ready
**Checkpoint E**: EPIC complete.
## 5. Acceptance Criteria
- [ ] All deliverables done
- [ ] All TEST- entries pass
- [ ] Resume Instructions = "N/A - EPIC Complete"
- [ ] No orphan ID references
- [ ] Branch merged or PR approved
Example EPIC- entry:
EPIC-01: User Authentication
State: Planned
Lifecycle: v0.7 Build Execution
Branch: epic/EPIC-01-auth
## 0. Context Capsule
### Resource Envelope
| Dimension | Target | Notes |
|-----------|--------|-------|
| Pre-load Context | ~40k tokens | Auth SoT + API specs + schema |
| Working Room | ~160k tokens | Plenty of space |
| Session Goal | Checkpoint C1 | Database schema complete |
### Dependencies
| Type | Items | Status |
|------|-------|--------|
| Requires | None | First EPIC |
| External | Supabase project | Ready |
| Enables | EPIC-02, EPIC-03 | Blocked until this completes |
### Pre-load Checklist
- [ ] SoT/SoT.BUSINESS_RULES.md — IDs: BR-001, BR-002
- [ ] SoT/SoT.API_CONTRACTS.md — IDs: API-001 to API-005
- [ ] SoT/SoT.TECHNICAL_DECISIONS.md — IDs: TECH-003, ARC-003
## 1. Session State (The "Brain Dump")
### Current State
- **Last Action**: N/A (not started)
- **Stopping Point**: N/A
- **Next Steps**:
1. Create branch epic/EPIC-01-auth
2. Begin with Phase A: Plan
3. Load context from pre-load checklist
- **Blockers**: None
- **Decisions Made**: Using Supabase Auth per TECH-003
### Resume Instructions
> Start fresh: create branch and load context per pre-load checklist.
## 2. Objective & Scope
Goal: Enable users to sign up, log in, and manage their sessions.
Deliverables:
- [ ] User registration with email/password
- [ ] Login/logout functionality
- [ ] Session management with refresh tokens
- [ ] Password reset flow
Out of Scope: Social auth (EPIC-02), team invites (EPIC-05)
## 3. Context & IDs
| Type | IDs |
|------|-----|
| Business Rules | BR-001, BR-002 |
| User Journeys | UJ-000, UJ-010 |
| APIs | API-001 to API-005 |
| Data Models | DBT-010, DBT-011 |
| Architecture | ARC-003, TECH-003 |
| Features | FEA-010, FEA-011 |
| Tests | TEST-001 to TEST-015 |
## 4. Execution Plan
### Phase A: Plan
- [ ] Context loaded
- [ ] Dependencies verified (Supabase ready)
- [ ] Strategy: Database → API → UI
- [ ] Branch created: epic/EPIC-01-auth
**Checkpoint A**: Planning complete, branch exists.
### Phase C: Build
Window 1: Database Schema
- [ ] Create users table with RLS
- [ ] Create sessions table
- [ ] Set up Supabase Auth triggers
**Checkpoint C1**: Schema deployed, migrations tested.
Window 2: API Endpoints
- [ ] POST /auth/signup (API-001)
- [ ] POST /auth/login (API-002)
- [ ] POST /auth/logout (API-003)
- [ ] POST /auth/refresh (API-004)
- [ ] POST /auth/reset-password (API-005)
**Checkpoint C2**: All endpoints return correct responses.
Window 3: UI Integration
- [ ] Signup form (SCR-001)
- [ ] Login form (SCR-002)
- [ ] Password reset flow (SCR-003)
- [ ] Auth state management
**Checkpoint C3**: Full auth flow works E2E.
## 5. Acceptance Criteria
- [ ] All deliverables done
- [ ] TEST-001 to TEST-015 pass
- [ ] Resume Instructions = "N/A - EPIC Complete"
- [ ] UJ-000 and UJ-010 verified manually
- [ ] Branch merged
EPIC Phase Structure
Each EPIC follows 5 phases:
| Phase | Purpose | Activities |
|---|---|---|
| A: Plan | Load context | Read EPIC, load referenced IDs, verify Session State |
| B: Design | Update SoT | Draft/refine ID entries in SoT/ before coding |
| C: Build | Implement | Work through Context Windows, test-first |
| D: Validate | Verify | Run tests, manual checks, traceability audit |
| E: Finish | Clean up | Update SoT, archive temp/, mark complete |
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Epic explosion | 20+ EPICs for MVP | Consolidate; most MVPs need 3-7 |
| One mega-EPIC | Everything in one EPIC | Split by architectural boundary |
| No ID references | EPIC without BR-, API-, DBT- links | Every EPIC must reference SoT/ |
| Circular dependencies | EPIC-01 needs EPIC-02 needs EPIC-01 | Identify shared foundation, extract to EPIC-00 |
| Context overload | Agent can't hold full EPIC context | Split into smaller Context Windows |
| Missing sequencing | No build order defined | Establish explicit dependency chain |
| Vague objectives | "Build the backend" | Specific, measurable: "Implement API-001–005" |
| Silent scope assumptions | EPIC assigns items without explaining boundary rationale | Every ambiguous assignment must note "API-XXX placed here because [reason]; alternative was EPIC-YYY" |
Quality Gates
Before proceeding to Test Planning:
- All API- and DBT- entries assigned to EPICs
- No orphaned specifications (everything has an EPIC home)
- Dependencies form a DAG (no circular dependencies)
- Each EPIC has clear, measurable deliverables
- Context Windows defined for each EPIC
- Sequencing makes sense (foundations first)
Downstream Connections
EPIC- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| Test Planning | EPIC scope defines test boundaries | TEST- entries for EPIC-01 scope |
| Implementation Loop | EPIC is execution unit | Work happens inside EPIC context |
| Session Management | Session State section tracks progress | Resume from where we left off |
| Progress Tracking | EPIC state shows overall progress | 3/7 EPICs complete |
Detailed References
- Epic scoping examples: See
references/examples.md - EPIC- entry template: See
assets/epic.md - Dependency mapping guide: See
references/dependency-mapping.md
Implementation Loop
Position in workflow: v0.7 Test Planning → v0.7 Implementation Loop → v0.8 Release
Consumes
This skill requires prior work from v0.7 Epic Scoping and v0.7 Test Planning:
- EPIC-* entries (from v0.7 Epic Scoping) — EPIC context, objectives, Context & IDs table, execution plan phases, Session State tracking
- TEST-* test specifications (from v0.7 Test Planning) — Acceptance criteria in Given-When-Then format; tests define "done" for each deliverable
- API-* endpoint contracts (referenced in EPIC Context & IDs) — Implementation targets with request/response shapes, error codes, constraints
- DBT-* schema specifications (referenced in EPIC Context & IDs) — Data model, field types, relationships, constraints to implement
- BR-* business rules (referenced in EPIC Context & IDs) — Product logic constraints to enforce in code
- Existing SoT files (if brownfield) — Durable specs that guide implementation without re-research
This skill assumes EPIC- and TEST- entries are complete, with all upstream IDs fully specified.
Produces
This skill updates/creates:
- Working code (implementation of API-, DBT-, BR-, tested against TEST-) — Runnable code with @implements tags tracing back to specifications; passes all TEST- for EPIC
- Updated SoT entries (if implementation reveals changes) — When building reveals new constraints or edge cases, update API-/DBT-/BR- entries immediately (not deferred)
- Session State updates (EPIC.md Section 1) — "Brain dump" tracking exact stopping point, Next Steps for resume, blockers, decisions, Context
- Development Graph (
status/devgraph.json) — the@implements/@verifiestags you write are harvested into bridge edges, producing the as-built layer that readiness scores (implementation_coverage,architecture_conformance) and the HeartBeat visualizer renders. Schema:docs/DEVELOPMENT_GRAPH.md.
All implementation outputs are code and live SoT, not confidence-based. They are:
- Traceable (every function tagged with @implements pointing to specification ID)
- Tested (all TEST- for EPIC pass before marking phase/EPIC complete)
- SoT-synchronized (implementation matches specs/ or specs/ updated to match implementation reality)
- Session-state-preserved (Session State section allows seamless resume from exact stopping point)
Example code with traceability (from EPIC-01):
// @implements API-001 (POST /users)
// @see BR-001 (email uniqueness), BR-002 (password requirements), DBT-010 (users table)
export async function createUser(req: Request, res: Response) {
// @implements BR-002 (password validation)
const passwordResult = validatePassword(req.body.password);
if (!passwordResult.valid) {
return res.status(400).json({
error: { code: 'INVALID_PASSWORD', message: passwordResult.errors[0] }
});
}
// @implements BR-001 (email uniqueness check)
const existingUser = await db.users.findByEmail(req.body.email);
if (existingUser) {
return res.status(409).json({
error: { code: 'EMAIL_EXISTS', message: 'User already exists' }
});
}
// @implements DBT-010 (users table creation)
const user = await db.users.create({
email: req.body.email,
passwordHash: await hashPassword(req.body.password),
createdAt: new Date(),
});
return res.status(201).json({ data: { id: user.id, email: user.email } });
}
Example Session State update (EPIC-01 mid-session):
## 1. Session State (The "Brain Dump")
- **Last Action**: Completed API-001–003 implementation; all tests passing. Password reset flow complete.
- **Stopping Point**: src/api/auth/reset.ts:85 — need to add rate limiting per BR-005
- **Next Steps**:
1. Add rate limiter middleware to password reset endpoint (BR-005)
2. Update TEST-012 to verify rate limiting (5 attempts per hour)
3. Run full test suite for EPIC-01
4. Move to API-005 (verify email endpoint)
- **Blockers**: None
- **Context**: Decided to implement rate limiting in middleware rather than at function level for reuse across endpoints. Using `express-rate-limit`.
- **Decisions Made**: POST /reset-password should return 429 with retry-after header when limit exceeded (API-001 error response spec). Using Redis for distributed rate limit tracking.
### Resume Instructions
> 1. Load EPIC-01 context (done in previous session)
> 2. Create new branch session if needed
> 3. Begin with Step 3 above (add rate limiter middleware)
> 4. When complete, run: `npm run test -- tests/api/auth.test.ts`
> 5. Update this Session State with new stopping point
This skill executes the build. It's the iterative cycle of: Load Context → Test → Code → Tag → Update → Validate → Repeat.
The Core Loop (The Heartbeat)
Each pass leaves a trace: step 5 tags code with @implements, and those tags are exactly what the Development Graph harvests — so this loop literally produces the pulse the HeartBeat visualizer shows (built → 🟢, unbuilt → 🔴, drifted → 🔴). Rerun readiness.py run after a Context Window to watch implementation_coverage move.
┌─────────────────────────────────────────────────────────────┐
│ 1. LOAD CONTEXT │
│ Read EPIC, referenced IDs, Session State │
│ → Can you state this session's goal in one sentence │
│ with specific IDs? If not, clarify before proceeding. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. SELECT FOCUS │
│ Choose a Context Window from Phase C │
│ → Pick the smallest scope that yields a verifiable │
│ outcome. One TEST- passing > three half-implemented. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. WRITE TEST (Red) │
│ Implement TEST- entry, watch it fail │
│ → Assertions must derive from TEST-/API-/BR- specs. │
│ Missing detail = spec gap — flag it, don't guess. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. WRITE CODE (Green) │
│ Implement to pass test │
│ → Minimum code to pass. No TEST- requires it? Don't │
│ build it. No speculative features or error handling. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. TAG CODE │
│ Add // @implements ID comments │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 6. UPDATE SoT │
│ Update specs/ if implementation reveals changes │
│ → Only update specs YOUR implementation changed. │
│ Don't "improve" adjacent specs you happened to read. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 7. VALIDATE │
│ Run tests, check traceability │
│ → Name the specific TEST- IDs that pass. "It works" │
│ is not validation — cite IDs. │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 8. UPDATE SESSION STATE │
│ Write to Session State before stopping │
└──────────────────────────┬──────────────────────────────────┘
│
└──────────► REPEAT until EPIC complete
Session State Protocol (MANDATORY)
Before ending ANY session, update the EPIC Session State section:
## 0. Session State (The "Brain Dump")
- **Last Action**: [What was just completed]
- **Stopping Point**: [Exact file:line or test failure]
- **Next Steps**: [Exact instructions for next session]
- **Context**: [Key decisions, blockers, open questions]
Good Example:
- **Last Action**: Completed API-002 (login endpoint), all tests passing
- **Stopping Point**: src/api/auth/login.ts:47 — need to add rate limiting
- **Next Steps**:
1. Add rate limiter middleware per BR-005
2. Update TEST-008 to verify rate limiting
3. Move to API-003 (logout)
- **Context**: Decided to use Supabase's built-in rate limiting rather than custom middleware
Assumptions & Ambiguities: During implementation, log assumptions and ambiguities in the EPIC's structured table (see EPIC template). This makes "Think Before Coding" persistent across sessions.
Example row during implementation:
| 3 | API-001 | ASSUMPTION | Response includes created_at field | Spec says "user object" but doesn't enumerate fields | Implemented with created_at; needs spec update |
Bad Example:
- **Last Action**: Working on auth
- **Stopping Point**: Somewhere in the code
- **Next Steps**: Continue
- **Context**: N/A
Code Traceability Protocol
Every major code unit MUST declare which ID it implements:
// @implements API-001 (Create User endpoint)
// @see BR-001 (Email uniqueness)
// @see DBT-001 (Users table)
export async function createUser(data: CreateUserInput): Promise<User> {
// Implementation...
}
Traceability Tag Patterns
| Code Element | Tag Pattern | Example |
|---|---|---|
| API handler | @implements API-XXX | API endpoint function |
| Business logic | @implements BR-XXX | Validation, rules |
| Database model | @implements DBT-XXX | Schema definition |
| UI component | @implements SCR-XXX | Screen component |
| Test file | @tests TEST-XXX | Test implementation |
| Cross-reference | @see [ID] | Related specification |
Example with Full Traceability
// @implements API-001 (POST /users)
// @see BR-001 (email uniqueness)
// @see BR-002 (password requirements)
// @see DBT-001 (users table)
export async function createUser(req: Request, res: Response) {
// @implements BR-002
const passwordResult = validatePassword(req.body.password);
if (!passwordResult.valid) {
return res.status(400).json({ error: passwordResult.errors });
}
// @implements BR-001
const existingUser = await db.users.findByEmail(req.body.email);
if (existingUser) {
return res.status(409).json({ error: { code: 'EMAIL_EXISTS' } });
}
// @implements DBT-001
const user = await db.users.create({
email: req.body.email,
passwordHash: await hashPassword(req.body.password),
});
return res.status(201).json({ data: user });
}
SoT Update Rules
The Source of Truth (specs/) must stay in sync with implementation:
| Situation | Action |
|---|---|
| Spec matches implementation | No update needed |
| Implementation reveals new constraint | Add BR- entry to specs/ |
| API shape changed during build | Update API- entry |
| New field needed in schema | Update DBT- entry |
| Spec was wrong/incomplete | Fix spec AND code |
| Discovered edge case | Add to spec, add TEST- |
Rule: Update specs during implementation, not "later."
Counter-rule: Only update specs that YOUR current work directly affects. If you notice that API-020 has a typo while working on API-001, log it in the Assumptions & Ambiguities table for a future session. Do not fix it now. Unplanned spec changes create invisible scope creep and break traceability for any parallel work.
Context Window Navigation
Work through Context Windows sequentially within an EPIC:
## 4. Context Windows
### Window 1: Database Schema ← CURRENT
- [x] Create users table migration
- [x] Add RLS policies
- [ ] Create sessions table
- [ ] Verify schema in studio
### Window 2: API Endpoints
- [ ] Implement API-001 (signup)
- [ ] Implement API-002 (login)
- [ ] Implement API-003 (logout)
### Window 3: UI Integration
- [ ] Build signup form
- [ ] Build login form
- [ ] Add auth state management
Test-First Development (Red-Green-Refactor)
Phase 1: Red (Write Failing Test)
// tests/api/users.test.ts
// @tests TEST-001
describe('POST /api/users', () => {
it('creates user with valid data', async () => {
const response = await request(app)
.post('/api/users')
.send({ email: 'test@example.com', password: 'ValidPass123!' });
expect(response.status).toBe(201);
expect(response.body.data.email).toBe('test@example.com');
// Test FAILS because endpoint doesn't exist yet
});
});
Constraint: If the test requires details not in the TEST- spec (response field names, error codes, status codes), look them up in API-/BR- specs. Do not invent them. If the spec lacks the detail, log an AMBIGUITY in the Assumptions & Ambiguities table before proceeding.
Phase 2: Green (Make Test Pass)
Write the minimum code to make the test pass:
// @implements API-001
export async function createUser(req, res) {
const user = await db.users.create(req.body);
return res.status(201).json({ data: user });
}
Constraint: "Minimum code" means literally what makes this one test go green. No additional validation, no extra error handling, no service layer abstractions unless a TEST- requires that behavior. This feels uncomfortable. That is correct.
Phase 3: Refactor (Improve Code Quality)
Now improve the code while tests stay green:
// @implements API-001
// @see BR-001, BR-002
export async function createUser(req, res) {
const validated = validateUserInput(req.body); // Add validation
if (!validated.ok) return res.status(400).json(validated.error);
const user = await userService.create(validated.data); // Extract service
return res.status(201).json({ data: user });
}
Constraint: Refactor only code you just wrote. Do not "improve" existing code that was already working. Do not extract abstractions unless you have 3+ concrete uses (not hypothetical future uses). Do not touch files outside the current focus area. See references/behavioral-examples.md for detailed good/bad comparisons.
EPIC Phases (Detailed)
Phase A: Plan (Load Context)
- Read EPIC file
- Review all referenced IDs (BR-, API-, DBT-)
- Check Session State section
- Review Assumptions & Ambiguities table for unresolved items
- Verify git branch is correct
- Confirm dependencies are complete
- Can state session goal in one sentence with specific IDs
If you cannot articulate what this session accomplishes in terms of specific TEST- or API- IDs, you are not ready to build. Refine the goal until it names IDs.
Phase B: Design (Update Specs)
- Draft/refine any unclear specs
- Add missing details discovered during planning
- Create TEST- entries if not done
- Update EPIC Context & IDs section
Phase C: Build (Context Windows)
For each Context Window:
- Select focus area
- Write tests for this window
- Implement code
- Add traceability tags
- Run tests, verify passing
- Update Session State
Phase D: Validate
- All TEST- entries for this EPIC pass
- Manual verification of UJ- journeys
-
@implementstags present in all major code units - No orphaned code (everything traces to an ID)
- specs/ updated to match implementation
Phase E: Finish (Harvest)
- Move useful temp/ notes to specs/ or archive/
- Verify all specs/ files match final code
- Clean Session State section
- Update EPIC state to Complete
- Log completion in Change Log
- Commit with message:
feat(EPIC-XX): [summary]
Red Flags (Stop and Fix)
| Signal | Action |
|---|---|
| Can't write test | Requirement unclear → revisit spec |
| Test keeps failing | Implementation wrong OR spec wrong → investigate |
| Need code outside EPIC scope | Wrong EPIC boundaries → re-scope |
| Lost context mid-session | Load Session State, verify EPIC context |
| Spec and code diverging | Stop, update spec to match reality |
| Test is testing implementation | Rewrite to test behavior |
| Writing code not required by any TEST- | Speculative — remove it, or write the TEST- first |
| Editing files outside current Context Window | Scope creep — note in Assumptions & Ambiguities table, defer |
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Test-after | Code written, then "add tests" | Write TEST- implementation first |
| Spec drift | Code diverges from specs/ | Update SoT during implementation |
| Missing traceability | Code has no @implements tags | Add tags as you write |
| Session amnesia | No Session State update | ALWAYS update before stopping |
| Context switching | Jumping between EPICs | Finish one EPIC before starting another |
| One-shot building | No iteration, just code dump | Follow the loop: test → code → tag |
| Orphaned code | Code not linked to any ID | Every function serves an ID |
| Speculative error handling | try/catch for scenarios no TEST- covers | Remove it. If the scenario matters, write TEST- first. |
| Drive-by improvements | "While I was here, I also improved..." | Revert non-essential changes. Note in Assumptions & Ambiguities table. |
| Vague completion claims | "Auth is working" without naming IDs | Always cite IDs: "TEST-001 through TEST-005 pass. API-001, API-002 verified." |
Quality Gates
Before marking EPIC complete:
- All TEST- entries pass
- All code has @implements tags
- specs/ matches implementation
- Session State is clean
- Manual UJ- verification done
- Change Log updated
- Development Graph green —
status/devgraph.jsonrebuilt;implementation_coverage≥ threshold (no scoped spec unbuilt, nounbuilt_specscap) and noarchitecture_conformanceviolations
Downstream Connections
Implementation Loop outputs feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| v0.8 Release | Completed EPICs ready for deployment | All TEST- pass, SoT current |
| Code Review | @implements tags for context | Reviewer knows which BR- to check |
| Readiness (v0.7) | Development Graph build-vs-blueprint | implementation_coverage + architecture_conformance from status/devgraph.json |
| HeartBeat | The Development Graph as a live pulse | Renders built / unbuilt / drifted across the codebase |
| Future Sessions | Session State for continuity | Resume exactly where left off |
| Maintenance | Traceability for debugging | "Which BR- does this code implement?" |
Detailed References
- Implementation examples: See
references/examples.md - Traceability patterns: See
references/traceability.md - Session state guide: See
references/session-state.md - Behavioral examples (good/bad): See
references/behavioral-examples.md
Test Planning
Position in workflow: v0.7 Epic Scoping → v0.7 Test Planning → v0.7 Implementation Loop
Consumes
This skill requires prior work from v0.7 Epic Scoping and v0.6 specifications:
- EPIC-* entries (from v0.7 Epic Scoping) — EPIC scope defines test boundaries; test plan must cover all APIs/BRs/UJs within EPIC Context & IDs section
- API-* endpoint contracts (from v0.6 Technical Specification) — Each endpoint has request/response shape and error codes that must be tested
- DBT-* data model specifications (from v0.6 Technical Specification) — Schema constraints, relationships, and business rules enforce data integrity tests
- BR-* business rules (from v0.3 Commercial Model) — Each rule must have at least one test verifying positive (rule allows) and negative (rule blocks) cases
- UJ-* user journey entries (from v0.4 User Journeys) — Critical journeys need E2E tests verifying complete flow from trigger to value moment
This skill assumes EPIC- entries are complete with full API-/DBT-/BR-/UJ- references in Context & IDs section.
Produces
This skill creates/updates:
- TEST-* entries (test case specifications, automation path) — Concrete, verifiable test cases with Given-When-Then format, test type, and coverage mapping to upstream IDs
- Test coverage matrix (per EPIC) — Validation showing every API- endpoint, BR- rule, and core UJ- journey has TEST- entries; identifies gaps
- Test automation specification — For each Critical/High priority TEST-, identifies test file path and automation framework (unit/integration/E2E)
All TEST- entries are acceptance criteria specifications, not confidence-based. They are:
- Derivable from upstream IDs (every TEST- ties to specific API-/BR-/UJ-/DBT-)
- Executable (Given-When-Then format is testable; automation paths are specified)
- Complete for acceptance (passing all TEST- for EPIC means EPIC is done)
- Focused on behavior (tests what the system does, not implementation details)
Example TEST- entry (API endpoint test):
TEST-001: User creation succeeds with valid data
Type: Integration
Tests: API-001 (POST /users), BR-001 (email uniqueness), DBT-010 (users table)
EPIC: EPIC-01
Given: No user with email "test@example.com" exists, database ready
When: POST /api/users with { email: "test@example.com", password: "Valid123!" }
Then:
- Response status: 201 Created
- Response body contains user id and email
- User record exists in DBT-010 (users table)
- Password is hashed, not plaintext
- Email verification email queued
Validation Method: Automated
Automation: tests/api/users.test.ts (Integration test)
Priority: Critical
Example TEST- entry (Business rule test):
TEST-005: Password validation enforces minimum length
Type: Unit
Tests: BR-002 (password requirements)
EPIC: EPIC-01
Given: Password validation function configured per BR-002
When: Validate password "weak" (length 4)
Then:
- Returns validation failure
- Error message: "Password must be at least 8 characters"
- No user record created
Validation Method: Automated
Automation: tests/unit/validation.test.ts
Priority: High
Example TEST- entry (User journey E2E test):
TEST-010: Onboarding journey completes successfully
Type: E2E
Tests: UJ-000 (onboarding), API-001 (signup), API-002 (login), SCR-001 (dashboard)
EPIC: EPIC-01
Given: New user on signup page, all services ready
When: User enters email/password → submits → verifies email → enters profile info → confirms
Then:
- User redirected to dashboard (SCR-001)
- Welcome message displayed with user name
- User session is active and persisted
- KPI-001 (activation) event tracked with timestamp
- UJ-000 completion confirmed
Validation Method: Both (Automated + manual verification of final state)
Automation: tests/e2e/onboarding.spec.ts
Priority: Critical
Core Principle: Test-First
Tests are not an afterthought. They are the contract that defines what "done" means. If you can't write the test, you don't understand the requirement.
Write TEST- entries before writing code. This forces clarity about what you're building.
If you cannot write a concrete Given-When-Then for a specification, the requirement is ambiguous. Do not write a vague test and move on. Instead, identify the specific ID (API-XXX, BR-XXX) that is unclear, note the competing interpretations, and log an AMBIGUITY in the EPIC's Assumptions & Ambiguities table. A test you cannot write precisely is more valuable as a flagged gap than a test you write by guessing.
Test Types
| Type | What It Tests | When to Use | Scope |
|---|---|---|---|
| Unit | Single function/method | Business logic, calculations | Smallest unit |
| Integration | Component boundaries | API ↔ Database | Module level |
| E2E | Full user flow | Critical journeys | System level |
| Contract | API shape/types | External integrations | Interface level |
| Performance | Speed/load | Critical paths | Benchmark |
Coverage Requirements
| ID Type | Minimum Coverage | Rationale |
|---|---|---|
| API- | 1 happy path + 1 error case per endpoint | Endpoints are integration points |
| BR- | 1 test per rule, including boundary cases | Rules are product logic |
| UJ- | 1 E2E test per core journey | Journeys are user value |
| DBT- | Constraint tests for critical fields | Data integrity is foundational |
Test Planning Process
-
Pull EPIC- scope
- Which APIs, DBTs, BRs are included?
-
For each API-: Define request/response tests
- Happy path: Valid input → expected output
- Error cases: Invalid input, auth failures, not found
- Verify first: Can you state the exact response body shape and every error code from the spec? If API- says "returns error" without specifying the code/shape, flag it: "API-XXX spec missing [specific gap]." Do not invent details.
-
For each BR-: Define rule validation tests
- Positive: Rule allows expected behavior
- Negative: Rule blocks invalid behavior
- Boundary: Edge cases at limits
-
For each UJ-: Define end-to-end flow tests
- Complete journey from trigger to value moment
-
For each DBT-: Define data integrity tests
- Constraints enforced (unique, not null)
- Relationships maintained (FK integrity)
-
Create TEST- entries linked to implementation IDs
-
Add TEST- references back to EPIC-
TEST- Output Template
TEST-XXX: [Test Name]
Type: [Unit | Integration | E2E | Contract | Performance]
Tests: [API-XXX | BR-XXX | UJ-XXX | DBT-XXX]
EPIC: [EPIC-XXX]
Given: [Preconditions — initial state]
When: [Action/trigger — what happens]
Then: [Expected outcome — what should result]
Validation Method: [Automated | Manual | Both]
Automation: [Test file path when implemented]
Priority: [Critical | High | Medium | Low]
Example TEST- entries:
TEST-001: User creation succeeds with valid data
Type: Integration
Tests: API-001 (POST /users), BR-001 (email uniqueness)
EPIC: EPIC-01
Given: No user with email "test@example.com" exists
When: POST /api/users with { email: "test@example.com", password: "Valid123!" }
Then:
- Response status: 201 Created
- Response body contains user id and email
- User record exists in DBT-010 (users)
- Password is hashed (not plaintext)
Validation Method: Automated
Automation: tests/api/users.test.ts
Priority: Critical
TEST-002: User creation fails with duplicate email
Type: Integration
Tests: API-001, BR-001 (email uniqueness)
EPIC: EPIC-01
Given: User with email "existing@example.com" already exists
When: POST /api/users with { email: "existing@example.com", password: "Valid123!" }
Then:
- Response status: 409 Conflict
- Response body: { error: { code: "EMAIL_EXISTS", message: "..." } }
- No new user record created
Validation Method: Automated
Automation: tests/api/users.test.ts
Priority: Critical
TEST-003: User creation fails with weak password
Type: Unit
Tests: BR-002 (password requirements)
EPIC: EPIC-01
Given: Password validation function
When: Validate password "weak"
Then:
- Returns false
- Error message indicates minimum length requirement
Validation Method: Automated
Automation: tests/unit/validation.test.ts
Priority: High
TEST-010: Onboarding journey completes successfully
Type: E2E
Tests: UJ-000 (onboarding)
EPIC: EPIC-01
Given: New user on signup page
When: User completes signup → email verification → profile setup
Then:
- User arrives at dashboard (SCR-001)
- Welcome message displayed
- User session is active
- KPI-001 (activation) event tracked
Validation Method: Both (Automated + Manual verification)
Automation: tests/e2e/onboarding.spec.ts
Priority: Critical
Test Priority Framework
| Priority | Criteria | Example |
|---|---|---|
| Critical | Breaks core value, data loss possible | Auth, payments, data creation |
| High | Blocks key journey, user-facing error | Onboarding, main features |
| Medium | Degrades experience, workaround exists | Settings, secondary features |
| Low | Edge case, admin-only, cosmetic | Rare scenarios, admin tools |
Writing Good Given-When-Then
Good Examples
Given: User is logged in and has 3 existing reports
When: User clicks "Create Report" and fills required fields
Then: 4 reports now exist, new report appears at top of list
Given: User has reached the free tier limit of 5 reports
When: User attempts to create a 6th report
Then: Error message shows "Upgrade to create more reports"
Create button is disabled
Upgrade CTA is displayed
Bad Examples
Given: The system is working
When: User does something
Then: It works correctly
(Too vague — what does "working" mean?)
Given: User
When: API
Then: Success
(No specifics — useless as a test spec)
Suspicious: Looks Good But Smuggles Assumptions
Given: User has 3 reports, account is on "Pro" plan
When: User clicks "Export All" and selects "PDF"
Then: 3 PDF files generated, each under 10MB, with company logo
Ask: Does BR-XXX or API-XXX actually specify PDF format? Does any spec mention a 10MB limit or company logo? If these details came from the agent's assumptions rather than spec IDs, the test is encoding unreviewed requirements. Either add the details to the spec (making them reviewable) or remove them from the test.
Test Categories by EPIC Phase
For Database Schema (Window 1)
TEST-XXX: [Table] enforces [constraint]
TEST-XXX: [Table] allows valid data
TEST-XXX: RLS policy restricts access correctly
For API Endpoints (Window 2)
TEST-XXX: [Method] [Path] returns [status] for [scenario]
TEST-XXX: [Method] [Path] enforces [BR-XXX]
TEST-XXX: [Method] [Path] handles [error case]
For UI Integration (Window 3)
TEST-XXX: [Screen] loads data from [API-XXX]
TEST-XXX: [Form] validates input per [BR-XXX]
TEST-XXX: [UJ-XXX] completes end-to-end
Anti-Patterns to Avoid
| Anti-Pattern | Signal | Fix |
|---|---|---|
| Tests after code | "We'll add tests later" | Define TEST- before writing code |
| Only happy path | No error case tests | Every API needs at least 1 error test |
| Orphaned tests | TEST- not linked to API-/BR-/UJ- | Every test must trace to a spec ID |
| Test explosion | 200+ tests for MVP | Focus on critical paths; 30-50 typical |
| Vague assertions | "System works correctly" | Specific, measurable outcomes |
| No automation path | Manual-only critical tests | Critical tests must be automatable |
| Testing implementation | Test verifies internal details | Test behavior, not implementation |
| Tests from assumptions | TEST- contains details not in any spec | Every assertion must trace to API-/BR-/UJ-. Missing detail? Fix the spec first. |
Quality Gates
Before proceeding to Implementation Loop:
- Every API- endpoint has at least 2 TEST- entries (happy + error)
- Every BR- rule has at least 1 TEST- entry
- Every core UJ- journey has an E2E TEST-
- Critical tests are marked for automation
- TEST- entries added to EPIC Context & IDs section
- Every assertion in TEST- entries traces to a specific detail in an upstream spec (no invented response shapes, error codes, or thresholds)
- Total test count is reasonable (30-50 for MVP)
Downstream Connections
TEST- entries feed into:
| Consumer | What It Uses | Example |
|---|---|---|
| Implementation Loop | TEST- defines acceptance criteria | EPIC done when TEST-001–010 pass |
| EPIC Validation (Phase D) | TEST- list for validation checklist | Run all TEST- for EPIC |
| CI/CD | TEST- becomes automated suite | TEST- entries → test files |
| Code Review | TEST- as review checklist | "Does PR pass TEST-005?" |
Detailed References
- Test planning examples: See
references/examples.md - TEST- entry template: See
assets/test.md - Test type decision guide: See
references/test-types.md
Changelog as Marketing
Position in workflow: v0.8 Release Planning → v0.8 Changelog as Marketing → v0.9 Launch Channels (ORB)
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | One release format (markdown for site); one channel mapping; minimum-viable changelog page |
| standard | Release categorization + 2–3 channel mappings; per-channel format templates; publish cadence; attribution plan |
| deep | Full categorization taxonomy; format templates for all relevant channels (email, blog, Twitter, LinkedIn, RSS, Slack); cadence + voice guide; KPI- attribution per channel |
What This Does
Treats the changelog as a distribution surface, not an engineering record. Each shipped release becomes a content artifact that lands across Owned and Rented channels with minimal extra effort. This is the bridge between v0.8 (what shipped) and v0.9 (where it gets told).
Done well, this is one of the highest-leverage Owned-channel investments — Stripe, Linear, Vercel, and Sentry have shown that an opinionated changelog drives ongoing inbound that compounds over years. Done badly, it's a dumping ground for "fixed bug X" that nobody reads.
How It Works
- Define the changelog audience(s) — Engineering changelogs (for users running self-hosted or integrating an API), customer-facing changelogs (for end-users), and internal changelogs (for the team) have different shapes. Anchor to the Positioning best-fit segment.
- Categorize release content — Each shipped item gets a category:
- New feature (publish loudly)
- Improvement (publish, briefly)
- Breaking change (publish, prominently, with migration path)
- Deprecation (publish, with timeline)
- Fix (publish only if user-visible)
- Internal (don't publish externally)
- Map categories to channels — Each category gets a channel destination from the ORB mix:
- New feature → Blog post + email + Twitter + LinkedIn
- Breaking change → Email (high-priority) + RSS + blog
- Improvement → Blog (digest) + Twitter (digest)
- Fix → Changelog page only
- Build per-channel format templates — Each channel has a length/tone constraint:
- Email: subject line + 2-paragraph body + CTA
- Blog: full writeup, screenshots, code samples
- Twitter/X: 280 chars, one image
- LinkedIn: 1,000-1,500 chars, professional voice
- Slack/Discord: short with link to blog
- RSS: full content for engineering audiences
- Set publish cadence — Per-release (every shipped release publishes immediately) vs. digest (weekly/monthly roll-up). Most teams need both: per-release for big things, digest for the rest.
- Plan attribution — Every channel-published release gets a UTM. Track changelog → signup conversion to identify which categories convert.
Example
A developer-tools product ships:
| Item | Category | Channels |
|---|---|---|
New /api/v2/webhooks endpoint | New feature | Blog (full), email, Twitter, LinkedIn, RSS |
/api/v1/webhooks deprecation (sunset in 6mo) | Deprecation | Email (high-priority), blog, RSS |
| 30% faster response time on heavy queries | Improvement | Twitter, weekly digest |
| Fixed: webhook signing edge case | Fix | Changelog page only |
| Internal: refactored auth middleware | Internal | (none) |
Tuesday publish:
- Blog post: "Webhooks v2 is live — here's what changed and how to migrate"
- Email to API customers (segment-targeted, not full list): "Action needed: webhook v1 sunset"
- Twitter: "Webhooks v2 ships today. v1 is sunset in 6 months. Migration guide: [link]"
- Changelog page: all five items (including the fix and internal note marked appropriately)
What You Get Back
- MON-CHG-* changelog entries (one per shipped release) — Master record with category, audience, channel mapping, links to per-channel publications
- GTM-CHG-* per-channel formats (one per channel) — Templates and example content
- Publish cadence schedule — Per-release vs. digest decisions
- KPI attribution plan — UTMs and conversion tracking
When to Use It
| Trigger | Mode |
|---|---|
| First release post-launch (no changelog system yet) | quick |
| Standard launch cadence stabilizing | standard |
| Pre-investor / pre-Series A — changelog as proof of velocity | deep |
| API or developer-tool product | deep (changelog is a primary surface) |
| One-time announcements (acquisition, big feature) | standard |
Consumes
- DEP-* release entries (from v0.8 Release Planning) — What's being released, when
- FEA-* features (from v0.3) — What new features exist; categorization input
- GTM-* channel mix (from v0.9 Launch Channels ORB, when available) — Where to publish
- GTM-* positioning (from v0.9 Positioning, when available) — Voice and tone constraints
- PER-* best-fit characteristics — Audience tone calibration
- KPI-* baselines — Attribution targets
When this skill runs before v0.9 has executed, channel mapping uses placeholder channels and is reconciled when v0.9 channels are finalized.
Produces
- MON-CHG-* entries in
SoT/SoT.DEPLOYMENT.md(or a dedicatedSoT/SoT.CHANGELOG.mdif release volume warrants) - GTM-CHG-* entries with
Type=Channel-Changelog(per-channel format templates) - CFD-* gaps surfaced — If a release category lacks an obvious channel mapping, log as research gap
Output Template
MON-CHG-XXX: Release — [Release name / version]
Type: Changelog
Date: YYYY-MM-DD
Owner: [Person / role]
Status: [Drafted | Reviewed | Published]
Released items:
- [Item 1] — Category: [New feature | Improvement | Breaking change | Deprecation | Fix | Internal]
- [Item 2] — Category: ...
Audience: [API customers | All users | Internal team | Mixed]
Channel publications:
- Blog: [URL or "scheduled YYYY-MM-DD"]
- Email: [Segment + scheduled date]
- Twitter: [Scheduled date]
- LinkedIn: [Scheduled date]
- Changelog page: [Updated YYYY-MM-DD]
Attribution: utm_campaign=changelog-<version>
Linked IDs: DEP-AAA (release), FEA-BBB (features shipped), GTM-CHG-CCC (channel formats), KPI-DDD (attribution)
GTM-CHG-XXX: Channel Format — [Channel name]
Type: Channel-Changelog
Channel: [Blog | Email | Twitter | LinkedIn | RSS | Slack]
Owner: [Person / role]
Format constraints:
Length: [chars / words / sections]
Tone: [Conversational | Technical | Formal — anchored in Positioning voice]
Visuals: [Required / optional]
CTA: [Specific action expected]
Template:
[Reusable template for this channel, with variable placeholders]
Example (most recent use):
[Concrete example from MON-CHG-XXX]
Publish trigger: [Per-release | Weekly digest | Monthly digest]
Linked IDs: MON-CHG-AAA (latest use), GTM-YYY (positioning voice)
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Dumping internal commits | Changelog reads like git log | Categorize; publish only what users care about |
| Same content everywhere | Same blog post copy-pasted to Twitter and LinkedIn | Each channel has its own format constraints; honor them |
| Vague feature claims | "Various improvements" | Name the specific change; "30% faster heavy queries" beats "performance improvements" |
| Engineering-only voice | Customer changelog uses internal jargon | Tone-shift per audience; engineer changelog ≠ end-user changelog |
| No attribution | Changelog publishes but no idea what converts | UTM every link; track per-channel conversion |
| Sporadic cadence | Publish heavily for 2 months, then quiet for 6 | Pick per-release or digest cadence; commit to it |
| Breaking change buried | Hidden in a sea of small items | Breaking changes get a dedicated, prominent slot |
Quality Gates
Before publishing the first release:
- Audience(s) defined (engineering, customer-facing, internal — separately if needed)
- Categorization scheme exists (at minimum: new / improvement / breaking / fix)
- Channel mapping table exists (categories → channels)
- Per-channel format templates exist
- Publish cadence committed
- Attribution plan (UTM convention) defined
- Voice/tone honors GTM- positioning (if v0.9 is done)
Downstream Connections
| Consumer | What it uses | Example |
|---|---|---|
| Launch Channels (ORB) | Changelog is an Owned channel; rolls into mix matrix | Blog-changelog = Owned-content |
| Launch Metrics | Per-channel changelog conversion targets | KPI-changelog-blog-signups |
| Feedback Loop Setup | Changelog reader comments become CFD- | Blog comment threads → CFD- pattern |
| AEO Audit | High-traffic changelog posts become AI citation sources | Changelog entries cited by AI search |
| v1.0 Case Study Builder | Shipped features in changelog feed case study material | "How we use [feature] at [customer]" |
Detailed References
- Stripe changelog: stripe.com/changelog — the canonical example
- Linear changelog: linear.app/changelog — opinionated voice
- Vercel changelog: vercel.com/changelog — visual-heavy
- jonathimer's
changelog-updatesskill (devmarketing-skills) - (No bundled
references/— read the source examples for current best practice)
Drift: Baseline / Compare / History
Position in workflow: v0.8 Monitoring Setup → v0.8 Drift: Baseline / Compare / History → v0.8 Runbook Creation
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | One metric / config / dataset baselined; weekly compare schedule; simple threshold alert |
| standard | 3–5 things monitored; baseline + tiered thresholds (warn / critical); compare cadence; history retention |
| deep | Full portfolio; multi-dimensional comparison (per segment, per environment); regression-cause matrix; auto-baselining after intentional change |
What This Does
Generalizes a pattern AgriciDaniel's claude-seo skill encodes for SEO drift — baseline → snapshot → compare → history — into a reusable monitoring shape that works for any metric, config, or dataset that can change over time and needs to be watched.
This is drift monitoring, distinct from alerting on absolute thresholds. Alerting answers "is X over the line right now?" Drift monitoring answers "is X different from last week's normal?" — which catches slow regressions that absolute thresholds miss.
Examples of things worth drift-monitoring:
- KPI: activation rate week-over-week
- AI search position: ChatGPT/Perplexity ranking for target queries
- Config: feature-flag rollout percentages
- Performance: p95 latency by endpoint
- Cost: per-user infra cost
- Marketing: per-channel CAC trend
- Content: changelog post engagement
- Third-party: vendor pricing pages (price hikes), competitor feature pages (parity loss)
How It Works
- Pick what to monitor — One thing per MON-DRIFT- entry. Must be:
- Quantifiable (number, percentage, list, configuration value)
- Snapshotable (captureable at a point in time, ideally automatically)
- Causally interpretable (when it changes, you know enough to investigate)
- Capture the baseline — Take a snapshot. Date it. Store in version control or a known location (
status/baselines/,monitoring/snapshots/, etc.). - Define drift thresholds:
- Warn: meaningful change (e.g., 10% drift in a KPI; any change in a config value)
- Critical: serious change (e.g., 25% KPI drop; breaking config change)
- Recalibrate: intentional change that should refresh the baseline (e.g., after a feature rollout, the baseline is wrong; refresh it)
- Set compare cadence — How often does this get re-snapshotted?
- Hot (hourly/daily): production KPIs, AI search positions during a launch
- Warm (weekly): standard product KPIs, content engagement
- Cool (monthly): vendor pricing, competitor feature parity, infra cost
- Build the compare procedure — A script or runbook that:
- Takes a new snapshot
- Diffs against baseline
- Computes drift % per dimension
- Emits warn/critical signals at thresholds
- Appends to history log
- Plan auto-baselining after intentional change [standard+] — When the team makes a deliberate change (ships a feature that should improve activation), the old baseline becomes wrong. Define what triggers a baseline refresh and who approves it.
Example
Monitoring AI search position for the target query "best CRO tool for SaaS founders" across 3 surfaces. (Generalized from AEO Audit re-test cadence.)
Baseline (2026-04-01):
ChatGPT: not mentioned (rank: --)
Perplexity: rank 4 of 5, miscategorized as "analytics"
AI Overviews: not mentioned
Sources cited: [competitor1.com, competitor2.com, reddit.com/r/SaaS]
Thresholds:
- Warn: rank changes by ≥1, sources list changes, miscategorization persists
- Critical: dropped from any surface where previously mentioned
Compare cadence: weekly during launch month, monthly after.
Re-snapshot (2026-04-15):
ChatGPT: rank 3 of 5 (NEW) ← improved
Perplexity: rank 3 of 5, category corrected (NEW) ← improved
AI Overviews: rank 5 of 7 (NEW) ← improved
Sources cited: [+ ourdomain.com (NEW), ...]
Compare output: 3 surfaces improved. Likely cause: alternatives-pages campaign + new CRO-anchored blog post indexed.
History append: 2026-04-01 → 2026-04-15 row added to history log.
Action: No alert; positive drift. Baseline can stay (next compare in 2 weeks). If the trend reverses, the baseline catches it.
What You Get Back
- MON-DRIFT-* entries (one per monitored thing) — Baseline snapshot, thresholds, cadence, compare procedure, history pointer
- History logs in
status/drift-history/<id>.jsonl(or similar) — Append-only record of compare results - Compare scripts (
scripts/drift/<id>.shor equivalent) when automatable
When to Use It
| Trigger | Mode |
|---|---|
| Post-launch — need ongoing watch on KPIs | standard |
| AEO Audit results to maintain | standard |
| Competitor feature parity tracking | standard |
| Vendor / third-party pricing watch | quick |
| Performance regression hunting | deep |
| Infrastructure cost trend | quick |
Do not use for things that are already covered by threshold-based alerting (RED/USE metrics, MON-* alerts). Drift is for trends; alerting is for absolutes.
Consumes
- MON-* monitoring infrastructure (from v0.8 Monitoring Setup) — Data sources for KPI/performance drift; existing dashboards
- KPI-* metric definitions (from v0.3 + v0.9) — What's worth watching
- CFD-* competitor research (from v0.2 + ongoing) — For competitor-parity drift
- GTM-AEO-* Coverage Matrix (from v0.9 AEO Audit) — For AI search position drift
- BR-PRICING-* (from v0.3 + v0.9 Offer) — For pricing drift on our side; vendor-pricing drift watches their side
- DEP-* release entries — Intentional changes that may trigger baseline refresh
Produces
- MON-DRIFT-* entries with
Type=Drift-Baseline— One per monitored thing - History logs in
status/drift-history/— Append-only diff history - Compare scripts in
scripts/drift/(when automatable) - Baseline-refresh approvals — Recorded when an intentional change resets a baseline
Output Template
MON-DRIFT-XXX: Baseline — [What is being monitored]
Type: Drift-Baseline
Category: [KPI | AI-Search | Config | Performance | Cost | Vendor | Competitor]
Owner: [Person / role]
Status: Active
Subject: [Specific thing — e.g., "ChatGPT rank for query 'best CRO tool for SaaS'"]
Baseline (YYYY-MM-DD):
[Snapshot — values, list, config dump, etc.]
Thresholds:
Warn: [Condition — e.g., "rank change ≥1 OR sources list changes"]
Critical: [Condition — e.g., "dropped from any surface previously mentioned"]
Recalibrate-trigger: [What intentional change resets the baseline]
Compare cadence: [Hourly | Daily | Weekly | Monthly | Triggered]
Compare procedure: [Script path OR manual runbook reference]
History: status/drift-history/<id>.jsonl
Re-snapshot history:
- YYYY-MM-DD: [summary of last compare result]
- YYYY-MM-DD: ...
Linked IDs: MON-XXX (data source), KPI-YYY or CFD-ZZZ or GTM-AEO-AAA (subject)
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Stale baseline | Comparing today's value against a 12-month-old baseline that no longer reflects "normal" | Add recalibrate-trigger conditions; refresh after intentional changes |
| Drift alerting on noise | Critical alert fires every week for 2% movement | Threshold is too tight; widen warn, tighten critical |
| No history log | Snapshot, compare, alert, forget | Append-only history is the whole point; without it, you can't see trends |
| Monitoring everything | 50 MON-DRIFT-* entries, nobody reads any | Pick the 3–5 things that matter; archive the rest |
| No causal interpretation | "Drift detected" with no investigation path | Each drift signal should map to candidate causes (recent release, competitor move, AI surface change) |
| Drift instead of alerting | Using drift for things that need absolute thresholds | Drift = trends; absolutes (latency > 500ms) = alerting |
Quality Gates
Before activating drift monitoring:
- Subject is quantifiable and snapshotable
- Baseline captured with explicit date
- Warn and critical thresholds defined
- Compare cadence committed
- Compare procedure (script or runbook) exists
- History log path defined and writable
- Recalibrate-trigger documented (when does baseline get refreshed?)
- Owner assigned
Downstream Connections
| Consumer | What it uses | Example |
|---|---|---|
| Runbook Creation (RUN-) | Drift criticals trigger investigation runbooks | MON-DRIFT-AEO critical → RUN-investigate-aeo-loss |
| Launch Metrics | Drift on launch KPIs informs go/no-go decisions | KPI-activation drift ≥10% → re-look at GTM |
| Feedback Loop Setup | Drift in customer-facing metrics drives CFD- investigation | Activation drift down → CFD- interview cohort |
| v0.9 AEO Audit (re-run) | Drift in AI search positions triggers re-audit | AEO drift → re-run aeo-audit |
| v1.0 Continuous Discovery | Drift patterns inform discovery questions | "Why is X drifting?" → Teresa Torres discovery |
Detailed References
- AgriciDaniel's
seo-driftskill — original baseline/compare/history pattern for SEO - Site Reliability Engineering (Google) — SLO-burn-rate alerting (related but different)
- (No bundled
references/— pattern is reusable; the content lives in each MON-DRIFT- entry)
Marketing-Ops Handoff (Lead Lifecycle + Sales Routing)
Position in workflow: v0.8 Monitoring Setup → v0.8 Marketing-Ops Handoff → v0.9 Launch Channels (ORB), v0.9 Cold Outreach
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | 3-stage lifecycle (Anonymous → Lead → Customer); single handoff rule; SLA per stage |
| standard | Full 5-stage lifecycle (Anonymous → MQL → SQL → Opportunity → Customer); entry/exit criteria; handoff payload spec; SLAs |
| deep | Full lifecycle + per-segment routing (by ICP / region / size); scoring model; rejection-loop rules; SLA monitoring + escalation |
What This Does
Defines the lifecycle stages a lead passes through from first touch to customer (or churn), plus the handoff rules at each transition. Without this, marketing-captured leads get dropped, double-worked, or never followed up. With this, you have an auditable definition of who owns what at each moment.
This skill applies primarily to B2B and prosumer products with a human-touch sales motion (founder-led sales, BDR/SDR teams, customer-success-led expansion). Pure self-serve products use a simpler version: lifecycle = Anonymous → Trial → Paid, with no human handoff.
How It Works
- Pick the lifecycle shape — Match the product:
- Self-serve: Anonymous → Signup → Activated → Paid → Expanded
- Sales-assisted: Anonymous → MQL → SQL → Opportunity → Customer
- Hybrid (PLG + Sales): Anonymous → Signup → Activated → Paid → SQL → Opportunity → Expansion
- Define entry criteria per stage — What event/behavior moves a lead into this stage? Examples:
- MQL: filled out a high-intent form, downloaded gated content, hit usage threshold
- SQL: explicit "talk to sales" or scoring threshold reached
- Opportunity: discovery call held, budget + authority confirmed
- Define exit criteria per stage — Two paths out: progress (to next stage) and disqualify (back to nurture or out). Disqualification rules matter as much as progression.
- Map ownership — Who owns the lead at each stage:
- Anonymous: marketing automation
- MQL: BDR/SDR
- SQL: AE / founder
- Opportunity: AE / founder
- Customer: CS / founder
- Define handoff payload — When a lead moves between owners, what context goes with them? At minimum:
- Source (which GTM-* channel produced this lead)
- Touchpoint history (what they've engaged with)
- Best-fit signals (firmographic match, behavioral fit)
- Disqualifiers (anything that ruled out an earlier stage)
- Open questions (what the next owner should clarify)
- Set SLAs per stage — How fast must the new owner respond after handoff? MQL → BDR typically <1 business hour for high-signal, <1 business day for low-signal. SQL → AE typically <30 minutes.
- Plan rejection routing — When SQL → AE handoff is rejected ("not a fit"), where does the lead go? Back to nurture, disqualified, requeued? Without this rule, leads die in limbo.
Example
B2B SaaS, $200/month entry price, sales-assisted motion.
| Stage | Entry criteria | Exit criteria | Owner | SLA |
|---|---|---|---|---|
| Anonymous | Any first touch | Filled form OR signed up | Marketing | n/a |
| MQL | Filled high-intent form (demo request, pricing page) | BDR qualifies in OR disqualifies | BDR | 1 business hour |
| SQL | BDR confirms fit + intent | AE accepts OR rejects | BDR → AE | 30 min |
| Opportunity | AE held discovery, budget + authority confirmed | Closed-won OR closed-lost | AE | 24 hr per touch |
| Customer | Closed-won contract signed | Churn OR expand | CS | Onboarding kickoff <1 business day |
Handoff payload at MQL → SQL (BDR → AE):
- Source: GTM-002 (Product Hunt) + retargeting
- Touchpoints: 3 blog posts, demo video, pricing page (3×)
- Best-fit signals: 50-person SaaS (matches PER-001), VP Eng signed up
- Disqualifiers: none
- Open questions: confirm budget owner; confirm timeline
Rejection routing at SQL → AE rejection ("too small"): lead returns to MQL queue with "small-team" tag; BDR can re-engage in 90 days if size signal changes.
What You Get Back
- BR-MOPS-* lifecycle rule entries — One per stage with entry/exit/owner/SLA
- GTM-MOPS-* handoff flow entries — One per transition (MQL→SQL, SQL→OPP, etc.) with payload spec
- Rejection-routing rules — Disqualifier-aware routing back to nurture
- SLA monitoring plan — Hooks into MON-DRIFT-* for SLA drift watching
When to Use It
| Trigger | Mode |
|---|---|
| B2B / sales-assisted product, pre-launch | standard |
| Hybrid PLG + Sales motion | deep |
| Pure self-serve consumer product | skip — overkill |
| Adding human sales to existing self-serve | standard |
| Sales velocity issues (leads dying in queue) | deep (rebuild with SLAs) |
| Pre-Series A audit (investor wants to see process) | deep |
Consumes
- PER-* best-fit characteristics (sharpened by v0.9 Positioning when available) — Defines what fit-signal scoring looks like
- GTM-* channel mix (from v0.9 Launch Channels ORB, when available) — Lead sources feed into Anonymous stage
- GTM-* offer card (from v0.9 Offer Construction) — Determines what "qualified" means (price tier sets bar)
- BR-PRICING-* (from v0.3 + v0.9) — Sets stage thresholds (above $X/year → SQL; below → self-serve)
- KPI-* baseline targets — Stage conversion targets feed into KPI- entries
When this skill runs before v0.9, channel and offer references use placeholders that get reconciled when v0.9 finalizes.
Produces
- BR-MOPS-* entries (lifecycle stage rules) in
SoT/SoT.BUSINESS_RULES.md - GTM-MOPS-* entries (handoff flow specs) — One per stage transition
- CFD-* gaps surfaced — When stage criteria can't be cleanly defined, log as research gap
Output Template
BR-MOPS-XXX: Lifecycle Stage — [Stage name]
Type: Lifecycle-Stage
Order: [#]
Status: Active
Stage: [Anonymous | Signup | Activated | MQL | SQL | Opportunity | Customer | Expansion]
Entry criteria:
- [Criterion 1 — e.g., "Filled out demo request form"]
- [Criterion 2 — e.g., "Reached usage threshold X"]
Exit criteria (progression):
- To [next stage]: [Criterion]
Exit criteria (disqualification):
- [Criterion that routes back to earlier stage or out]
Owner: [Marketing automation | BDR/SDR | AE | CS | Founder]
SLA:
Response time after entering this stage: [duration]
Escalation: [What happens if SLA missed]
Linked IDs: PER-XXX (fit signals), GTM-YYY (source channels), BR-PRICING-ZZZ (tier threshold), KPI-AAA (conversion rate)
GTM-MOPS-XXX: Handoff — [Stage A] → [Stage B]
Type: Handoff
Status: Active
From: [Stage A] (owner: ...)
To: [Stage B] (owner: ...)
Trigger: [Specific event — e.g., "BDR marks lead as Qualified in CRM"]
Payload (what context transfers):
- Source: [GTM-* channel]
- Touchpoint history: [What they engaged with]
- Best-fit signals: [Firmographic + behavioral match]
- Disqualifiers: [Anything that ruled out earlier stages]
- Open questions: [What new owner should clarify]
Rejection rule:
Condition: [When does the new owner reject this handoff?]
Routing: [Where does the rejected lead go? Nurture / disqualified / requeue]
Re-engagement: [Conditions under which this lead can return]
SLA: [Response time required from new owner]
Linked IDs: BR-MOPS-AAA (Stage A rule), BR-MOPS-BBB (Stage B rule)
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| MQL = "anyone who filled a form" | High-volume MQLs with 1% SQL conversion | Tighten MQL entry criteria; add fit-signal scoring |
| No rejection routing | Leads die when SQL → AE rejects | Define where rejected leads go (nurture, disqualified, requeue) |
| SLA without escalation | "Respond in 1 hour" with no consequence if missed | SLA must have an escalation path |
| Handoff without payload | New owner asks "who is this?" | Mandatory payload fields at every handoff |
| Stages without owners | "We'll figure out who handles SQLs later" | One owner per stage; named role minimum |
| Lifecycle for self-serve | $20/month consumer product with MQL/SQL/OPP | Use Signup → Activated → Paid; no human handoff |
| No SLA monitoring | SLAs exist on paper, missed in practice | Drift-monitor SLA via MON-DRIFT- |
Quality Gates
Before activating handoff:
- Lifecycle shape matches product motion (self-serve / sales-assisted / hybrid)
- Every stage has entry, exit-progression, and exit-disqualification criteria
- Every stage has a named owner (role minimum)
- Every stage has an SLA with escalation path
- Every transition has a handoff payload spec
- Rejection routing defined for every owner-changing handoff
- SLA drift monitoring set up via MON-DRIFT-
Downstream Connections
| Consumer | What it uses | Example |
|---|---|---|
| Launch Channels (ORB) | Each channel's leads enter the lifecycle at Anonymous | GTM-002 (Product Hunt) → Anonymous → MQL routing |
| Cold Outreach (Tiered) | Tier 1/2/3 sequences map to lifecycle stages | Tier 1 = SQL-tier ABM; Tier 3 = MQL nurture |
| Launch Metrics | Stage conversion rates become KPI- entries | KPI-MQL-to-SQL-conversion |
| Feedback Loop Setup | Rejected leads' "why we passed" reasons feed CFD- | Pattern: "too small" rejections → CFD- pricing signal |
| Drift Monitoring | SLA drift catches process decay | MON-DRIFT-MQL-response-SLA |
Detailed References
- alirezarezvani's
marketing-opsandrevenue-operationsskills (claude-skills) - Predictable Revenue (Aaron Ross) — sales handoff structure
- From Impossible to Inevitable (Aaron Ross + Jason Lemkin) — stage discipline
- SiriusDecisions lead-lifecycle framework (the canonical B2B reference)
- (No bundled
references/— lifecycle shapes vary; this skill encodes the discipline, not a specific shape)
Monitoring Setup
Position in workflow: v0.8 Runbook Creation → v0.8 Monitoring Setup → v0.9 GTM Strategy
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | RED metrics on critical path only; 3–5 alerts linked to RUN-; single overview dashboard |
| standard | RED + USE coverage; SLOs for tier-1 services; full alert routing to RUN-; dashboards by audience |
| deep | Layered coverage (RED + USE + business + UX); multi-tier SLOs with error budgets; baseline calibration from staging; escalation routing |
Consumes
This skill requires prior work from v0.8 Runbook Creation and earlier stages:
- RUN-* runbook entries (from v0.8 Runbook Creation) — Incident response runbooks define alerting scenarios; critical alerts must link to RUN- procedures
- DEP-* deployment entries (from v0.8 Release Planning) — DEP- rollback thresholds and post-deploy validation steps inform MON- alert conditions and SLO targets
- API-* endpoint contracts (from v0.6 Technical Specification) — Define baseline latency, throughput, and error rates for application-layer metrics
- KPI-* metrics (from v0.3 Outcome Definition and v0.9 Launch Metrics) — Business metrics (signups, conversions, retention) inform dashboard design and business layer monitoring
- ARC-* architecture decisions (from v0.6 Architecture Design) — System structure determines which components to monitor (monolith has different metrics than distributed services)
- TECH-* technology stack (from v0.5 Technical Stack Selection) — Technology choices (database, cloud provider, APM tools) determine available metrics and monitoring tools
This skill assumes DEP- and RUN- entries are complete with thresholds, rollback conditions, and incident procedures defined.
Produces
This skill creates/updates:
- MON-* entries (monitoring specifications, metric/alert/dashboard/SLO types) — Concrete monitoring rules with thresholds, alert conditions, dashboards, SLO definitions, linked to RUN- procedures
- Alert routing configuration — Mapping of MON- alerts to notification channels and teams; links alerts to RUN- incident procedures
- Observability baseline — Metrics gathered from staging/production, establishing normal operating ranges for alert thresholds
All MON- entries are operational monitoring specifications, not confidence-based. They are:
- Measurable (every metric has a source, unit, and aggregation method)
- Actionable (every alert has a RUN- procedure; no orphaned alerts)
- Thresholded (critical/warning severity with specific numeric conditions)
- Dashboarded (MON- dashboard entries provide visibility to operators and stakeholders)
- SLO-backed (SLO entries tie monitoring to product commitments)
Example MON- entries:
MON-001: API Request Latency (p95)
Type: Metric
Layer: Application
Owner: Backend Team
Name: api.request.latency.p95
Description: 95th percentile response time for all API endpoints (from API-001–020)
Unit: ms
Source: Application APM (Datadog custom instrumentation)
Aggregation: p95 over 5-minute window
Retention: 90 days
Linked IDs: API-001 to API-020, DEP-004 (baseline from staging)
---
MON-002: High Latency Alert (Warning)
Type: Alert
Layer: Application
Owner: Backend Team
Metric: MON-001 (api.request.latency.p95)
Condition: >500ms (from DEP-002 baseline)
Window: 5 minutes
Severity: Warning
Runbook: RUN-001 (Performance Degradation Investigation)
Notification:
- Channel: Slack #backend-alerts
- Recipients: Backend on-call, team notified during business hours
Silencing: During scheduled maintenance windows (DEP-004 notifications)
Linked IDs: MON-001, RUN-001, DEP-002
---
MON-003: Critical Latency Alert
Type: Alert
Layer: Application
Owner: Backend Team
Metric: MON-001 (api.request.latency.p95)
Condition: >2000ms (SLA breach, from KPI-001 target)
Window: 2 minutes
Severity: Critical
Runbook: RUN-001 (Performance Degradation Investigation)
Notification:
- Channel: PagerDuty (wake on-call)
- Recipients: Backend on-call, Tech Lead, escalate if not acknowledged in 5 min
Silencing: None (critical alerts never silenced)
Linked IDs: MON-001, RUN-001, KPI-001
---
MON-004: API Availability SLO
Type: SLO
Layer: Application
Owner: Platform Team
Objective: API endpoints return non-5xx response
Target: 99.9% uptime (from DEP-002 / KPI-001)
Window: Rolling 30 days
Error Budget: 43.2 minutes/month
Alerting:
- 50% error budget consumed → Warning to engineering (slow-burn alert)
- 75% error budget consumed → Critical, freeze non-essential deploys
- 100% error budget consumed → Post-incident review required (RUN-008 procedure)
Linked IDs: API-001–020, DEP-003 (rollback triggers), RUN-008 (incident review)
---
MON-005: System Health Dashboard
Type: Dashboard
Layer: Infrastructure + Application
Owner: Platform Team
Purpose: Quick health check for on-call engineers (run from RUN-002, RUN-001)
Audience: On-call engineers, engineering leadership, ops team
Panels:
- API Request Rate (last 1h): Should be steady or increasing
- API Latency (p50, p95, p99): Watch for p95/p99 creeping up
- Error Rate by Endpoint: Any 5xx > 0 is concerning
- Active Critical Alerts: Should be none
- Database Connection Pool (from MON-006): Trending toward threshold
- CPU/Memory by Service: Identify resource exhaustion
- Deployment Status: Current version, time of last deploy
Refresh: 30 seconds
Linked IDs: MON-001, MON-002, MON-003, MON-006, DEP-001, RUN-001/002
---
MON-006: Database Connection Pool Utilization
Type: Metric
Layer: Infrastructure
Owner: Database Team
Name: db.connection_pool.utilized_percent
Description: Percentage of available connections in use (from DEP-001 pool size)
Unit: percentage
Source: Database monitoring (RDS Enhanced Monitoring or custom query)
Aggregation: avg over 1-minute window
Retention: 30 days
Linked IDs: DEP-001 (pool config), RUN-001 (incident when >90%)
Core Concept: Monitoring as Early Warning
Monitoring is not about collecting data—it is about detecting problems before users do. Every metric should answer: "Is this working? If not, what's broken?"
Monitoring Layers
| Layer | What to Measure | Why It Matters |
|---|---|---|
| Infrastructure | CPU, memory, disk, network | System health foundation |
| Application | Latency, errors, throughput | User-facing performance |
| Business | Signups, conversions, revenue | Product health |
| User Experience | Page load, interaction time | Real user impact |
Execution
-
Define SLOs (Service Level Objectives)
- What uptime do we promise?
- What latency is acceptable?
- What error rate is tolerable?
-
Identify key metrics per layer
- Infrastructure: Resource utilization
- Application: RED metrics (Rate, Errors, Duration)
- Business: KPI- from v0.3 and v0.9
- User: Core Web Vitals, journey completion
-
Set alert thresholds
- Warning: Investigate soon
- Critical: Act immediately
- Base on SLOs and historical data
-
Map alerts to runbooks
- Every critical alert → RUN- procedure
- No alert without action path
-
Design dashboards
- Overview: System health at a glance
- Deep-dive: Per-service details
- Business: KPI tracking
-
Create MON- entries with full traceability
MON- Output Template
MON-XXX: [Monitoring Rule Title]
Type: [Metric | Alert | Dashboard | SLO]
Layer: [Infrastructure | Application | Business | User Experience]
Owner: [Team responsible for this metric/alert]
For Metric Type:
Name: [metric.name.format]
Description: [What this measures]
Unit: [count | ms | percentage | bytes]
Source: [Where this comes from]
Aggregation: [avg | sum | p50 | p95 | p99]
Retention: [How long to keep data]
For Alert Type:
Metric: [MON-YYY or metric name]
Condition: [Threshold expression]
Window: [Time window for evaluation]
Severity: [Critical | Warning | Info]
Runbook: [RUN-XXX to follow when fired]
Notification:
- Channel: [Slack, PagerDuty, Email]
- Recipients: [Team or individuals]
Silencing: [When to suppress, e.g., maintenance windows]
For Dashboard Type:
Purpose: [What questions this answers]
Audience: [Who uses this dashboard]
Panels: [List of visualizations]
Refresh: [How often to update]
For SLO Type:
Objective: [What we promise]
Target: [Percentage, e.g., 99.9%]
Window: [Rolling 30 days]
Error Budget: [How much downtime allowed]
Alerting: [When error budget is at risk]
Linked IDs: [API-XXX, UJ-XXX, KPI-XXX, RUN-XXX related]
Example MON- entries:
MON-001: API Request Latency (p95)
Type: Metric
Layer: Application
Owner: Backend Team
Name: api.request.latency.p95
Description: 95th percentile response time for all API endpoints
Unit: ms
Source: Application APM (Datadog/New Relic)
Aggregation: p95
Retention: 90 days
Linked IDs: API-001 to API-020
MON-002: High Latency Alert
Type: Alert
Layer: Application
Owner: Backend Team
Metric: MON-001 (api.request.latency.p95)
Condition: > 500ms
Window: 5 minutes
Severity: Warning
Runbook: RUN-006 (Performance Degradation Investigation)
Notification:
- Channel: Slack #backend-alerts
- Recipients: Backend on-call
Silencing: During scheduled deployments (DEP-002 windows)
Linked IDs: MON-001, RUN-006, DEP-002
MON-003: Critical Latency Alert
Type: Alert
Layer: Application
Owner: Backend Team
Metric: MON-001 (api.request.latency.p95)
Condition: > 2000ms
Window: 2 minutes
Severity: Critical
Runbook: RUN-006 (Performance Degradation Investigation)
Notification:
- Channel: PagerDuty
- Recipients: Backend on-call, Tech Lead
Silencing: None (always alert on critical)
Linked IDs: MON-001, RUN-006
MON-004: API Availability SLO
Type: SLO
Layer: Application
Owner: Platform Team
Objective: API endpoints return non-5xx response
Target: 99.9%
Window: Rolling 30 days
Error Budget: 43.2 minutes/month
Alerting:
- 50% budget consumed → Warning to engineering
- 75% budget consumed → Critical, freeze non-essential deploys
- 100% budget consumed → Incident review required
Linked IDs: API-001 to API-020, DEP-003
MON-005: System Health Dashboard
Type: Dashboard
Layer: Infrastructure + Application
Owner: Platform Team
Purpose: Quick health check for on-call engineers
Audience: On-call, engineering leadership
Panels:
- API Request Rate (last 1h)
- API Latency (p50, p95, p99)
- Error Rate by Endpoint
- Active Alerts
- Database Connection Pool
- CPU/Memory by Service
Refresh: 30 seconds
Linked IDs: MON-001, MON-002, MON-003
The RED Method (Application Monitoring)
For each service, measure:
| Metric | What It Measures | Alert Threshold |
|---|---|---|
| Rate | Requests per second | Anomaly detection |
| Errors | Failed requests / total | >1% warning, >5% critical |
| Duration | Request latency (p95, p99) | >500ms warning, >2s critical |
The USE Method (Infrastructure Monitoring)
For each resource (CPU, memory, disk, network):
| Metric | What It Measures | Alert Threshold |
|---|---|---|
| Utilization | % of capacity used | >80% warning, >95% critical |
| Saturation | Queue depth, waiting | >0 for critical resources |
| Errors | Error count/rate | Any errors = investigate |
SLO Framework
| Tier | Availability | Latency (p95) | Use For |
|---|---|---|---|
| Tier 1 | 99.99% (52 min/yr) | <100ms | Payment, auth |
| Tier 2 | 99.9% (8.7 hr/yr) | <500ms | Core features |
| Tier 3 | 99% (3.6 days/yr) | <2s | Background jobs |
Alert Severity Matrix
| Severity | User Impact | Response Time | Notification |
|---|---|---|---|
| Critical | Service unusable | <5 min | PagerDuty (wake up) |
| Warning | Degraded experience | <30 min | Slack (business hours) |
| Info | No immediate impact | Next day | Dashboard/log |
Dashboard Design Principles
| Principle | Implementation |
|---|---|
| Answer questions | Each panel answers "Is X working?" |
| Hierarchy | Overview → Service → Component |
| Context | Show thresholds, comparisons |
| Actionable | Link to runbooks from alerts |
| Fast | Quick load, auto-refresh |
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Alert fatigue | Too many alerts, team ignores | Tune thresholds, remove noise |
| No runbook link | Alert fires, no one knows what to do | Every alert → RUN- |
| Vanity metrics | "1 million requests!" without context | Focus on user-impacting metrics |
| Missing baselines | No historical comparison | Establish baselines before launch |
| Over-monitoring | 500 metrics, can't find signal | Focus on RED/USE fundamentals |
| Under-monitoring | "We'll add monitoring later" | Monitoring ships with code |
Quality Gates
Before proceeding to v0.9 GTM Strategy:
- SLOs defined for critical services (MON- SLO type)
- RED metrics configured for application layer
- USE metrics configured for infrastructure layer
- Critical alerts linked to RUN- procedures
- Overview dashboard created for on-call
- Alert notification channels configured
- Baseline metrics established from staging
Downstream Connections
| Consumer | What It Uses | Example |
|---|---|---|
| On-Call Team | MON- alerts trigger response | MON-003 → page engineer |
| v0.9 Launch Metrics | MON- provides baseline data | MON-001 baseline → KPI-010 target |
| Post-Mortems | MON- data for incident analysis | "MON-005 showed spike at 14:32" |
| Capacity Planning | MON- trends inform scaling | USE metrics → infrastructure planning |
| DEP- Rollback | MON- thresholds trigger rollback | MON-002 breach → DEP-003 rollback |
Detailed References
- Monitoring stack examples: See
references/monitoring-stack.md - MON- entry template: See
assets/mon-template.md - SLO calculation guide: See
references/slo-guide.md - Dashboard best practices: See
references/dashboard-guide.md
Release Planning
Position in workflow: v0.7 Implementation Loop → v0.8 Release Planning → v0.8 Runbook Creation
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | Staging→prod only; 3–5 release criteria; one rollback trigger |
| standard | Dev/staging/preview/prod environments; full criteria checklist; multiple rollback triggers; post-deploy validation |
| deep | Full environments + IaC review + canary/blue-green strategy + risk-weighted criteria + post-mortem hooks |
Consumes
This skill requires prior work from v0.7 Implementation Loop and v0.6-v0.9:
- EPIC-* completed entries (from v0.7 Implementation Loop) — Finished work packages define what's being released; must have State=Complete, all TEST- passing
- TEST-* test entries (from v0.7 Test Planning) — All TEST- must pass in staging before release criteria can be met
- API-* endpoint contracts (referenced in EPIC Context & IDs) — Define SLA and performance baselines for release criteria
- ENV-* environment specifications (from v0.6 Environment Setup) — Local/CI/CD/production configurations inform DEP- entries for each environment
- ARC-* architecture decisions (from v0.6 Architecture Design) — System structure (monolith, microservices, deployment topology) drives environment setup
- TECH-* technology stack (from v0.5 Technical Stack Selection) — Technology choices inform infrastructure requirements and deployment tooling
- RISK-* high-priority entries (from v0.5 Risk Discovery) — High RISK- must be mitigated or explicitly accepted before release
- KPI-* metrics (from v0.3 and v0.9) — Target KPI values inform monitoring baselines and rollback thresholds
This skill assumes v0.7 Implementation is complete with all EPIC- entries marked Complete and all TEST- passing.
Produces
This skill creates/updates:
- DEP-* entries (deployment specifications, environment/criteria/rollback/validation types) — Release readiness checklist with environment configs, go/no-go criteria, rollback triggers and thresholds, post-deploy validation steps
- Release readiness checklist — Pre-deploy validation matrix showing which DEP- criteria must be met before release proceeds
- Rollback decision tree — Mapping of DEP- rollback triggers to execution procedures and escalation paths (feeds v0.8 Runbook Creation)
All DEP- entries are operational contracts, not confidence-based. They are:
- Environment-specific (each environment from staging to production has defined configuration)
- Verifiable (each criterion has a concrete check or metric threshold)
- Enforceable (release stops if DEP- criteria not met)
- Traceable (each DEP- links to EPIC-, TEST-, API-, KPI- that validate it)
Example DEP- entries:
DEP-001: Production Environment Configuration
Type: Environment
Stage: Pre-deploy
Description: AWS production environment setup for application
Name: production
Infrastructure: AWS us-east-1, ECS Fargate, RDS PostgreSQL
Configuration:
- NODE_ENV=production
- LOG_LEVEL=info
- RATE_LIMIT=100/min
- METRICS_COLLECTION=enabled
Secrets: AWS Secrets Manager, rotated monthly
Access: DevOps team (deploy), On-call (read-only access)
Linked IDs: ARC-001 (monolith structure), TECH-005 (AWS)
---
DEP-002: All Tests Pass in Staging
Type: Criteria
Stage: Pre-deploy
Description: Complete test suite must pass in staging environment before production release
Requirement: All TEST- entries pass with >95% success rate, including smoke tests and E2E tests
Verification: CI/CD pipeline reports green; test report generated and reviewed
Blocker: Yes — Release cannot proceed if this fails
Owner: QA Lead
Linked IDs: TEST-001 to TEST-050 (from EPIC-01 through EPIC-07)
---
DEP-003: Error Rate Rollback Trigger
Type: Rollback
Stage: Post-deploy
Description: Automatic rollback if error rate exceeds baseline post-deployment
Trigger: 5xx error rate exceeds pre-deployment baseline
Threshold: >2% of requests for 5 minutes (currently 0.5% baseline from MON-001)
Procedure:
1. Alert on-call engineer (PagerDuty)
2. Pause traffic to new version
3. Revert to pre-deploy git tag
4. Investigate root cause
Notification: #incidents Slack, PagerDuty, Engineering Lead
Linked IDs: MON-001 (error rate metric), RUN-002 (rollback procedure), API-001–020 (endpoints affected)
---
DEP-004: Post-Deployment Smoke Tests
Type: Validation
Stage: Post-deploy
Description: Automated smoke tests to verify critical user journeys work post-deployment
Check: All critical UJ- (UJ-000, UJ-001, UJ-005, UJ-010) complete successfully
Method: Automated (tests/e2e/smoke.spec.ts) + manual spot-check
Success Criteria: All journeys complete <2 seconds, no auth failures, data persists
Escalation: If smoke tests fail, execute DEP-003 rollback and investigate
Linked IDs: UJ-000/001/005/010 (critical journeys), TEST-050 (E2E suite)
Core Concept: Release as Contract
A release is not "code that works locally." It is a contract between development and operations—a formal handoff that includes everything needed to deploy, validate, and recover.
Release Components
| Component | Purpose | Output |
|---|---|---|
| Deployment Environment | Where code runs | DEP- (environment config) |
| Release Criteria | What must be true to deploy | DEP- (checklist) |
| Rollback Triggers | When to revert | DEP- (conditions) |
| Validation Steps | How to verify success | DEP- (post-deploy checks) |
Execution
-
Inventory completed EPICs
- Which EPIC- entries are "Complete"?
- What API-, DBT-, FEA- are included in this release?
-
Define deployment environments
- Staging, Production, Preview
- Environment-specific configurations
- Secrets management approach
-
Establish release criteria
- All TEST- pass in staging
- Performance baselines met (from MON-)
- No critical RISK- blockers
- Security review complete
-
Define rollback triggers
- Error rate thresholds
- Latency thresholds
- User-reported critical issues
- Data integrity concerns
-
Document validation steps
- Post-deployment smoke tests
- Key journey verification (UJ-)
- Metric baseline confirmation
-
Create DEP- entries with full traceability
DEP- Output Template
DEP-XXX: [Deployment Item Title]
Type: [Environment | Criteria | Rollback | Validation | Step]
Stage: [Pre-deploy | Deploy | Post-deploy | Rollback]
Description: [What this deployment item covers]
For Environment Type:
Name: [staging | production | preview]
Infrastructure: [Cloud provider, region, resources]
Configuration: [Environment-specific settings]
Secrets: [How secrets are managed]
Access: [Who can deploy, who can access]
For Criteria Type:
Requirement: [What must be true]
Verification: [How to check this]
Blocker: [Yes | No] — Does failure block deploy?
Owner: [Who verifies]
For Rollback Type:
Trigger: [What condition initiates rollback]
Threshold: [Specific metric or condition]
Procedure: [How to execute rollback]
Notification: [Who to alert]
For Validation Type:
Check: [What to verify post-deploy]
Method: [Manual | Automated | Both]
Success Criteria: [Expected result]
Escalation: [What if validation fails]
Linked IDs: [EPIC-XXX, API-XXX, TEST-XXX related]
Example DEP- entries:
DEP-001: Production Environment Configuration
Type: Environment
Stage: Pre-deploy
Description: AWS production environment setup for main application
Name: production
Infrastructure: AWS us-east-1, ECS Fargate, RDS PostgreSQL
Configuration:
- NODE_ENV=production
- LOG_LEVEL=info
- RATE_LIMIT=100/min
Secrets: AWS Secrets Manager, rotated monthly
Access: DevOps team (deploy), On-call (read-only)
Linked IDs: ARC-001, TECH-005
DEP-002: All Tests Pass in Staging
Type: Criteria
Stage: Pre-deploy
Description: Complete test suite must pass in staging environment
Requirement: All TEST- entries pass with >95% success rate
Verification: CI/CD pipeline green status, test report review
Blocker: Yes
Owner: QA Lead
Linked IDs: TEST-001 to TEST-050
DEP-003: Error Rate Rollback Trigger
Type: Rollback
Stage: Post-deploy
Description: Automatic rollback if error rate exceeds threshold
Trigger: 5xx error rate exceeds baseline
Threshold: >2% of requests for 5 minutes
Procedure:
1. Alert on-call engineer
2. Pause traffic to new version (if canary)
3. Revert to previous known-good version
4. Investigate root cause
Notification: #incidents Slack, PagerDuty
Linked IDs: MON-001, RUN-005
Environment Progression
| Stage | Environment | Purpose | Gate |
|---|---|---|---|
| 1 | Development | Engineer testing | Tests pass locally |
| 2 | Staging | Integration testing | All TEST- pass |
| 3 | Preview | Stakeholder review | Sign-off from PM |
| 4 | Production | Live users | All DEP- criteria met |
Release Criteria Categories
| Category | Examples | Priority |
|---|---|---|
| Functional | Tests pass, features work | Must-have |
| Performance | Latency <200ms, throughput >100rps | Must-have |
| Security | No critical vulns, secrets rotated | Must-have |
| Operational | Runbooks ready, monitoring active | Should-have |
| Documentation | Release notes, API docs updated | Should-have |
Rollback Strategy Patterns
| Pattern | When to Use | Complexity |
|---|---|---|
| Blue-Green | Need instant rollback, can afford 2x infra | Medium |
| Canary | Gradual rollout, catch issues early | High |
| Rolling | Zero-downtime, standard approach | Low |
| Feature Flags | Decouple deploy from release | Medium |
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Deploy and pray | No validation steps defined | Add DEP- validation entries |
| Manual everything | No automation, error-prone | Automate repeatable steps |
| No rollback plan | "We'll figure it out" | Define triggers and procedures upfront |
| Environment drift | Staging doesn't match production | Infrastructure as code, sync configs |
| Missing criteria | "It works on my machine" | Formal DEP- criteria checklist |
| Unclear ownership | No one knows who approves | Assign owner to each DEP- |
Quality Gates
Before proceeding to Runbook Creation:
- All deployment environments documented (DEP- Environment type)
- Release criteria defined with clear blockers (DEP- Criteria type)
- Rollback triggers specified with thresholds (DEP- Rollback type)
- Post-deploy validation steps defined (DEP- Validation type)
- Each DEP- entry has an owner
- Criteria trace back to EPIC-, TEST-, API- IDs
Downstream Connections
| Consumer | What It Uses | Example |
|---|---|---|
| Runbook Creation | DEP- rollback procedures become runbook inputs | DEP-003 → RUN-005 |
| Monitoring Setup | DEP- thresholds inform alerting | DEP-003 (2% error) → MON-001 |
| v0.9 GTM Strategy | Release readiness gates launch | All DEP- met → GTM-001 |
| EPIC- Future Releases | DEP- becomes template for next release | DEP-001 reused |
Detailed References
- Environment configuration examples: See
references/environment-examples.md - DEP- entry template: See
assets/dep-template.md - Rollback procedure guide: See
references/rollback-guide.md
Runbook Creation
Position in workflow: v0.8 Release Planning → v0.8 Runbook Creation → v0.8 Monitoring Setup
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | 2–3 runbooks covering the top RISK-/MON- pairs |
| standard | Incident + deployment + maintenance runbooks linked to MON- and DEP-, with escalation paths |
| deep | Full matrix + drill schedule + recovery scenarios + tabletop exercise outputs |
Consumes
This skill requires prior work from v0.8 Release Planning and earlier stages:
- DEP-* deployment entries (from v0.8 Release Planning) — Deployment procedures from DEP- rollback/validation sections inform RUN- deployment and recovery runbooks
- RISK-* risk entries (from v0.5 Risk Discovery) — High/medium RISK- entries must have response runbooks; mitigations become procedures
- MON-* monitoring specifications (planned from v0.8 Monitoring Setup, or anticipated) — Key alerts from MON- (before formalization) inform incident response runbooks; runbooks will be referenced FROM monitoring
- ARC-* architecture decisions (from v0.6 Architecture Design) — System structure (single service vs microservices, databases, integrations) determines incident scope and escalation paths
- TECH-* technology stack (from v0.5 Technical Stack Selection) — Technology choices (database, cloud provider, APM tools) determine specific commands and tools in runbook procedures
- API-* endpoint contracts (from v0.6 Technical Specification) — For reference if incident involves specific endpoints or payloads
This skill assumes DEP- entries are complete with rollback procedures and post-deploy validation steps defined.
Produces
This skill creates/updates:
- RUN-* entries (operational runbooks, category-based) — Step-by-step procedures for incident response, deployment execution, maintenance tasks, recovery from failures, and escalation paths
- Incident response matrix — Mapping of scenarios (connection pool exhaustion, latency spike, deployment failure, etc.) to RUN- procedures
- Runbook cross-reference — Links from RUN- procedures to DEP- rollback conditions, anticipated MON- alerts, and RISK- entries they address
All RUN- entries are operational procedures, not confidence-based. They are:
- Executable (numbered steps with specific commands and tools)
- Verifiable (each step has a verification check confirming success)
- Scoped (explicit "Handles" and "Does NOT handle" sections)
- Escalatable (clear escalation paths and contact information)
- Tested (should be drilled regularly; includes "Last Tested" date)
Example RUN- entries:
RUN-001: Database Connection Pool Exhaustion
Category: Incident
Trigger: MON-005 alert (connection pool >90%) — from v0.8 Monitoring Setup
Owner: Backend Team
Last Tested: 2025-02-20
## Scope
- **Handles**: Connection pool saturation, slow queries causing pooling
- **Does NOT handle**: Database server crash (see RUN-010), Network failure (see RUN-011)
## Prerequisites
- [ ] Access to AWS RDS console
- [ ] PostgreSQL read credentials in LastPass
- [ ] PagerDuty access for escalation
- [ ] Datadog dashboard access (MON-005 source)
## Procedure
### Step 1: Verify Alert
Check current connection pool status:
Commands:
\`\`\`sql
SELECT count(*) FROM pg_stat_activity WHERE state = 'active';
SELECT * FROM pg_stat_activity WHERE state = 'active' ORDER BY query_start;
\`\`\`
Verification:
- [ ] Connection count ≥90% of max pool (check DEP-001 pool config)
### Step 2: Identify Problematic Queries
Find long-running or blocked queries:
Commands:
\`\`\`sql
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE (now() - pg_stat_activity.query_start) > interval '5 minutes';
\`\`\`
Verification:
- [ ] At least one query identified running >5 minutes
### Step 3: Kill Problematic Queries (if safe)
Only kill queries that are clearly stuck:
Commands:
\`\`\`sql
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE pid = <problematic_pid>;
\`\`\`
Verification:
- [ ] Connection count dropping within 2 minutes
- [ ] MON-005 alert resolving
### Step 4: Investigate Root Cause
- Check recent deployments (last 24h via git log)
- Review application logs for query patterns (Datadog logs)
- Check for missing indexes on recent queries
## Escalation
- **When to escalate**: Issue persists >15 minutes, data integrity concern, cannot kill queries safely
- **Who to contact**: Database Team Lead (Slack: @db-team, PagerDuty)
- **What to provide**: Timeline, queries identified, actions taken, connection count trend
## Post-Incident
- [ ] Document incident timeline (who was paged, when actions taken)
- [ ] File ticket for query optimization if needed
- [ ] Update this runbook if steps were wrong/missing
- [ ] Schedule team drill of this runbook within 1 week if escalated
Linked IDs: MON-005 (alert), DEP-001 (pool config), RISK-008 (data integrity)
---
RUN-002: Production Deployment Procedure
Category: Deployment
Trigger: Scheduled release when all DEP- criteria met
Owner: DevOps Team
Last Tested: 2025-02-18
## Scope
- **Handles**: Standard production deployments (mainline releases)
- **Does NOT handle**: Hotfix deployments (see RUN-003), Database migrations (see RUN-004), Emergency rollback (see RUN-005)
## Prerequisites
- [ ] All DEP- criteria verified
- [ ] DEP-002: All tests pass in staging
- [ ] DEP-003: No critical RISK- blockers
- [ ] DEP-004: Security review complete
- [ ] Staging deployment successful
- [ ] Release approval from Tech Lead in #deployments channel
- [ ] On-call engineer available for rollback (next 30 minutes)
## Procedure
### Step 1: Pre-Deploy Announcement
Notify stakeholders of upcoming deployment:
Commands:
\`\`\`bash
./scripts/notify-deploy.sh --env production --version v${VERSION} --channel #deployments
\`\`\`
Verification:
- [ ] Message posted to #deployments
### Step 2: Create Deployment Checkpoint
Tag current production for rollback (per DEP-003):
Commands:
\`\`\`bash
git tag -a "pre-deploy-$(date +%Y%m%d-%H%M)" -m "Checkpoint before v${VERSION}"
git push origin --tags
\`\`\`
Verification:
- [ ] Tag created and pushed to git
### Step 3: Execute Deployment
Deploy to production using CI/CD:
Commands:
\`\`\`bash
./scripts/deploy.sh --env production --version v${VERSION}
\`\`\`
Verification:
- [ ] Deployment pipeline exits with status 0
- [ ] New version visible: curl https://api.prod.example.com/health | jq .version
### Step 4: Post-Deploy Validation
Run smoke tests (per DEP-004):
Commands:
\`\`\`bash
./scripts/smoke-test.sh --env production --suite critical
\`\`\`
Verification:
- [ ] All smoke tests pass
- [ ] Manual spot-check: key UJ- flows work (test signup, login, create report)
- [ ] Error rate within baseline: curl https://api.prod.example.com/metrics | jq .error_rate_5m
### Step 5: Monitor for 30 Minutes
Watch dashboards for anomalies:
Verification:
- [ ] No new critical/warning alerts (check Datadog/Slack #alerts)
- [ ] Latency (MON-001) within normal range (<500ms p95)
- [ ] Error rate (MON-002) within baseline (<0.5%)
- [ ] Business metrics dashboard shows expected traffic
## Escalation
- **When to escalate**: Smoke tests fail, error rate >2%, user reports critical issue, latency >2s
- **Who to contact**: On-call engineer (PagerDuty), then Tech Lead
- **What to provide**: Version deployed, failure mode, logs from Datadog, timeline
## Post-Deployment
- [ ] Post deployment success to #deployments
- [ ] Update deployment log in runbook folder
- [ ] If issues: Escalate and execute RUN-005 (emergency rollback)
Linked IDs: DEP-001/002/003/004 (release criteria), RUN-005 (emergency rollback)
Core Concept: Runbook as Insurance
A runbook is not documentation—it is operational insurance. When systems fail at 3 AM, the runbook is the difference between 5-minute recovery and 5-hour chaos.
Runbook Categories
| Category | Purpose | Trigger |
|---|---|---|
| Incident Response | Handle production issues | Alert fires, user reports |
| Deployment | Execute release procedures | Scheduled release |
| Maintenance | Regular operational tasks | Scheduled windows |
| Recovery | Restore from failures | Disaster scenario |
| Escalation | Route to right people | Issue beyond capability |
Execution
-
Identify critical scenarios
- What alerts from MON- require action?
- What deployment steps from DEP- need procedures?
- What RISK- entries need response plans?
-
Map each scenario to a runbook
- One runbook per distinct scenario
- Clear scope—what it covers and doesn't
-
Document step-by-step procedures
- Numbered steps, no ambiguity
- Include commands, links, contact info
- Assume operator has minimal context
-
Define escalation paths
- When to escalate
- Who to contact
- What information to provide
-
Add verification steps
- How to confirm the issue is resolved
- What metrics should normalize
-
Create RUN- entries with full traceability
RUN- Output Template
RUN-XXX: [Runbook Title]
Category: [Incident | Deployment | Maintenance | Recovery | Escalation]
Trigger: [What initiates this runbook]
Owner: [Team or role responsible]
Last Tested: [Date of last drill/use]
## Scope
- **Handles**: [What scenarios this covers]
- **Does NOT handle**: [Explicit exclusions]
## Prerequisites
- [ ] Access to [system/tool]
- [ ] Credentials for [service]
- [ ] Contact info for [team]
## Procedure
### Step 1: [Action Title]
[Detailed instructions]
Commands:
```bash
# Example command with placeholders
Verification:
- [How to confirm step succeeded]
Step 2: [Action Title]
[Detailed instructions]
Step N: [Final Action]
[Detailed instructions]
Escalation
- When to escalate: [Conditions that require help]
- Who to contact: [Name/role, contact method]
- What to provide: [Information needed for handoff]
Post-Incident
- Document incident timeline
- Update runbook if steps were wrong/missing
- Schedule post-mortem if severity > [threshold]
Linked IDs: [MON-XXX, DEP-XXX, RISK-XXX related]
**Example RUN- entries:**
RUN-001: Database Connection Pool Exhaustion Category: Incident Trigger: MON-005 alert (connection pool >90%) Owner: Backend Team Last Tested: 2025-01-15
Scope
- Handles: Connection pool saturation, slow queries causing pooling
- Does NOT handle: Database server crash (see RUN-010)
Prerequisites
- Access to AWS RDS console
- Database read credentials
- PagerDuty access for escalation
Procedure
Step 1: Verify Alert
Check current connection pool status:
Commands:
SELECT count(*) FROM pg_stat_activity WHERE state = 'active';
SELECT * FROM pg_stat_activity WHERE state = 'active' ORDER BY query_start;
Verification:
- Connection count matches alert threshold
Step 2: Identify Problematic Queries
Find long-running or blocked queries:
Commands:
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE (now() - pg_stat_activity.query_start) > interval '5 minutes';
Step 3: Kill Problematic Queries (if safe)
Only kill queries that are clearly stuck:
Commands:
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE pid = <problematic_pid>;
Verification:
- Connection count dropping
- MON-005 alert resolving
Step 4: Investigate Root Cause
- Check recent deployments (last 24h)
- Review application logs for query patterns
- Check for missing indexes on recent queries
Escalation
- When to escalate: Issue persists >15 minutes, data integrity concern
- Who to contact: Database Team Lead (Slack: @db-team, PagerDuty)
- What to provide: Timeline, queries identified, actions taken
Post-Incident
- Document incident timeline
- File ticket for query optimization if needed
- Update this runbook if steps were wrong/missing
Linked IDs: MON-005, DEP-001, RISK-008
RUN-002: Production Deployment Procedure Category: Deployment Trigger: Scheduled release, all DEP- criteria met Owner: DevOps Team Last Tested: 2025-01-20
Scope
- Handles: Standard production deployments
- Does NOT handle: Hotfix deployments (see RUN-003), Database migrations (see RUN-004)
Prerequisites
- All DEP- criteria verified (DEP-002, DEP-003)
- Staging deployment successful
- Release approval in deployment channel
- On-call engineer available for rollback
Procedure
Step 1: Pre-Deploy Announcement
Notify stakeholders of upcoming deployment:
Commands:
# Post to #deployments Slack channel
./scripts/notify-deploy.sh --env production --version ${VERSION}
Step 2: Create Deployment Checkpoint
Tag current production for rollback:
Commands:
git tag -a "pre-deploy-$(date +%Y%m%d-%H%M)" -m "Checkpoint before ${VERSION}"
git push origin --tags
Step 3: Execute Deployment
Deploy to production using CI/CD:
Commands:
# Trigger production deploy pipeline
./scripts/deploy.sh --env production --version ${VERSION}
Verification:
- Deployment pipeline green
- New version visible in health check endpoint
Step 4: Post-Deploy Validation
Run smoke tests and verify key flows:
Commands:
./scripts/smoke-test.sh --env production
Verification:
- All smoke tests pass
- Key UJ- flows verified manually
- Error rate within baseline (MON-001)
Step 5: Monitor for 15 Minutes
Watch dashboards for anomalies:
- Error rate dashboard
- Latency dashboard
- Business metrics dashboard
Verification:
- No new alerts
- Metrics within normal range
Escalation
- When to escalate: Smoke tests fail, error rate >2%, user reports
- Who to contact: On-call engineer, then Tech Lead
- What to provide: Deployment version, failure mode, logs
Post-Incident
- Post deployment success/failure to #deployments
- Update deployment log
- Schedule retro if issues encountered
Linked IDs: DEP-001, DEP-002, DEP-003, MON-001
## Runbook Quality Checklist
For each runbook, verify:
| Criterion | Question | Pass? |
|-----------|----------|-------|
| **Actionable** | Can someone follow this without asking questions? | |
| **Complete** | Are all steps documented with commands? | |
| **Verifiable** | Does each step have a verification check? | |
| **Scoped** | Is it clear what this does and doesn't cover? | |
| **Escalatable** | Is the escalation path defined? | |
| **Tested** | Has this runbook been tested in a drill? | |
| **Maintained** | Is there an owner who updates it? | |
## Runbook Types by MON- Alert
Map monitoring alerts to runbooks:
| Alert Type | Runbook | Response Time |
|------------|---------|---------------|
| **Critical** | Dedicated incident RUN- | <5 min |
| **Warning** | Shared investigation RUN- | <30 min |
| **Info** | Reference documentation | Next business day |
## Common Procedures to Document
| Category | Must-Have Runbooks |
|----------|-------------------|
| **Incident** | Service down, Performance degradation, Security incident |
| **Deployment** | Standard release, Hotfix, Rollback |
| **Maintenance** | Database backup, Log rotation, Certificate renewal |
| **Recovery** | Data restore, Failover, Service restart |
## Anti-Patterns
| Pattern | Signal | Fix |
|---------|--------|-----|
| **Too vague** | "Investigate the issue" | Add specific commands and checks |
| **Too long** | 50+ step runbook | Split into focused runbooks |
| **Outdated** | References deprecated tools | Add review date, assign owner |
| **No verification** | Steps without confirmation | Add verification after each step |
| **Assuming knowledge** | "You know how to do this" | Write for someone's first day |
| **No escalation** | Dead ends with no help path | Always define escalation |
## Quality Gates
Before proceeding to Monitoring Setup:
- [ ] All critical scenarios have runbooks (RUN-)
- [ ] Each MON- alert maps to a RUN- procedure
- [ ] DEP- rollback triggers link to RUN- procedures
- [ ] RISK- high/medium entries have response runbooks
- [ ] All runbooks have owners and last-tested dates
- [ ] Escalation paths defined for all runbooks
## Downstream Connections
| Consumer | What It Uses | Example |
|----------|--------------|---------|
| **Monitoring Setup** | RUN- procedures linked from alerts | MON-001 → RUN-001 |
| **On-Call Team** | RUN- as operational reference | Night incident → RUN-001 |
| **Post-Mortems** | RUN- gaps inform improvements | "Runbook missing step" → Update RUN-001 |
| **Training** | RUN- for new engineer onboarding | Run drills using RUN-002 |
## Detailed References
- **Runbook examples by category**: See `references/runbook-examples.md`
- **RUN- entry template**: See `assets/run-template.md`
- **Incident response framework**: See `references/incident-framework.md`
AEO Audit (AI Search Discoverability)
Position in workflow: v0.9 Launch Channels (ORB) → v0.9 AEO Audit → v0.9 Alternatives Pages, Launch Metrics
Execution Mode
Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.
| Mode | What this skill produces |
|---|---|
| quick | 5 target queries × 2 AI surfaces (ChatGPT + Perplexity); top 3 gaps with fixes |
| standard | 10–15 queries × 3–4 AI surfaces; full Coverage Matrix; ranked fix backlog |
| deep | 20–30 queries × all major surfaces; per-surface citation analysis; structured-data audit; before/after re-test plan |
What This Does
Tests whether AI search engines surface, recommend, and accurately describe the product when a target customer asks a relevant question. AEO (answer-engine optimization) and GEO (generative-engine optimization) are the post-SEO distribution layer — when ChatGPT/Perplexity/AI Overviews answer a buyer's question, the product either is in the answer or isn't.
This is a diagnostic skill. It produces a gap map and a ranked fix backlog. The fixes are executed by prd-v09-alternatives-pages, content updates, and structured-data work — not by this skill.
How It Works
- Build a query set — From the Positioning best-fit characteristics (jobs to be done, triggers, search intent), generate target queries an actual best-fit buyer would type. Mix high-intent ("best X for Y"), comparison ("X vs Y"), and category ("what is X").
- Run each query against AI surfaces — At minimum: ChatGPT (free tier — what the median buyer sees), Perplexity, Google AI Overviews. Deep mode adds Claude, Brave Search, Kagi. Save raw responses with timestamps.
- Score each result on five dimensions:
- Mentioned? (yes / no)
- Position in recommendation list (1st, 2nd, not listed)
- Description accuracy (matches positioning vs. miscategorized vs. wrong)
- Competitive frame (which alternatives are listed alongside)
- Citation sources (which URLs/domains the AI cited to build the answer)
- Identify the gap pattern:
- Absence gaps — product not mentioned at all
- Category gaps — mentioned in the wrong category (positioning failure)
- Citation gaps — answer is built from sources the product doesn't appear in (need to be on those sources)
- Comparison gaps — competitor wins the comparison query because comparison content doesn't exist on your side
- Propose ranked fixes — Each fix maps to a specific gap type:
- Absence → content on best-fit query intent, JSON-LD structured data, citation-source targets
- Category → positioning content (handoff to Positioning skill)
- Citation → outreach/contribution to high-citation sources (G2, Reddit, blog posts on cited domains)
- Comparison → handoff to prd-v09-alternatives-pages
Example
A best-fit buyer types "best CRO tool for early-stage SaaS founders" into ChatGPT. Result:
| Surface | Mentioned? | Position | Accuracy | Citations |
|---|---|---|---|---|
| ChatGPT | No | n/a | n/a | 5 sources, none ours |
| Perplexity | Yes | 4th of 5 | "an analytics tool" (wrong category) | Sources include our pricing page only |
| AI Overviews | No | n/a | n/a | G2, Reddit r/SaaS, two competitor blog posts |
Gaps identified:
- Absence in ChatGPT — no high-intent landing for this query
- Category miscoding in Perplexity — we're being summarized as "analytics", not "CRO"
- Citation gap — we don't appear in G2 or r/SaaS threads about CRO
Ranked fixes:
- Publish CRO-anchored guide (prd-v09-alternatives-pages handles competitor variants)
- Rewrite product schema (JSON-LD) with the Dunford category claim
- Outreach to G2 (claim profile, request reviews) and post a substantive thread in r/SaaS
What You Get Back
- GTM-AEO-* entries — one per query × surface gap, with the proposed fix and ranking
- Coverage Matrix (single GTM-* with Type=Audit) — full query × surface × status table
- Fix backlog — ranked list with handoff target skills
When to Use It
| Trigger | Mode |
|---|---|
| Pre-launch sanity check (before paid channels activate) | quick |
| Standard launch wave audit | standard |
| Quarterly retention/competitive intelligence review | deep |
| After major positioning change (re-test) | standard |
| When organic signups stall and paid CAC rises | deep |
Do not run before Positioning is complete — without a sharpened category claim, every "miscategorized" result is unfixable.
Consumes
- GTM-* positioning statement + category claim (from v0.9 Positioning) — Defines what "accurate description" looks like; without this, scoring is opinion
- CFD-* competitive alternatives (from v0.2) — Source for comparison-intent queries
- PER-* best-fit characteristics (sharpened by Positioning) — Source for query intent
- GTM-* channel mix (from v0.9 Launch Channels) — AEO is a channel; surfaces tested should match best-fit channel use
Produces
- GTM-AEO-* entries with
Type=AEO-Recommendation, one per gap-fix pair - GTM-* with
Type=Audit— the Coverage Matrix - Fix backlog — handoff list referencing prd-v09-alternatives-pages, Positioning re-run, content production tickets
Confidence guidance (P4): AEO scoring is 3/5 minimum because it's based on observed AI responses, not opinion. Quick mode may produce 2/5 outputs (limited sampling) and must tag them.
Output Template
GTM-AEO-XXX: [Gap Title]
Type: AEO-Recommendation
Status: Open
Priority: [High | Medium | Low]
Owner: [Person / role]
Query: "[the exact query]"
Surface: [ChatGPT | Perplexity | AI Overviews | Claude | Brave | Kagi]
Date observed: [YYYY-MM-DD]
Result summary:
Mentioned? [yes | no]
Position: [#]
Accuracy: [matches positioning | miscategorized | wrong]
Competitive frame: [list of alternatives shown]
Citation sources: [URLs/domains used]
Gap type: [Absence | Category | Citation | Comparison]
Proposed fix:
- [Specific action 1]
- [Specific action 2]
Handoff: [Target skill or owner — e.g., prd-v09-alternatives-pages, content team]
Re-test: [Date to verify fix]
Linked IDs: GTM-YYY (positioning), CFD-ZZZ (competitor), PER-AAA (best-fit)
GTM-XXX: AEO Coverage Matrix
Type: Audit
Status: Snapshot — [YYYY-MM-DD]
| Query | ChatGPT | Perplexity | AI Overviews | Gap Type |
|-------|---------|------------|--------------|----------|
| ... | ✓ #2 | ✗ | ✗ | Absence (2 surfaces) |
| ... | ✗ | ✓ #4 (miscat) | ✗ | Category + Absence |
Total queries: X
Coverage rate: Y% (mentioned in any surface)
Accurate-description rate: Z% (mentioned AND correctly described)
Linked IDs: All GTM-AEO-* entries above
Anti-Patterns
| Pattern | Signal | Fix |
|---|---|---|
| Vanity queries | Auditing "best [exact product name]" — you'll always win that one | Use buyer-intent queries the buyer would actually type |
| No timestamp / no re-test | Results saved but never re-tested | AI surfaces change; re-test every fix within 2 weeks |
| Surface monoculture | Only testing ChatGPT | Each surface has different model/data; minimum 3 surfaces |
| Fix all gaps equally | 20 gaps, parallel work, no ranking | Rank by query buyer-intent strength × surface adoption |
| Treating absence as failure | "We're not in any results — game over" | Absence is often the easiest fix (publish high-intent content); category miscoding is the harder one |
| Skipping citation analysis | Knowing you're absent but not why | Citation sources reveal where you need to appear |
Quality Gates
Before proceeding to fix execution:
- At least 5 queries tested (quick) / 10–15 (standard) / 20+ (deep)
- At least 3 AI surfaces sampled (standard+)
- Every gap has a typed classification (Absence / Category / Citation / Comparison)
- Every gap has a proposed fix with a handoff target
- Coverage Matrix exists and is dated
- Fix backlog is ranked
Downstream Connections
| Consumer | What it uses | Example |
|---|---|---|
| Alternatives Pages | Comparison-gap fixes become alternatives-page targets | "X vs us" comparison gap → SCR-ALT- page |
| Positioning (re-run) | Category-coding gaps signal positioning weakness | Recurring miscategorization → re-run prd-v09-positioning-dunford |
| Launch Metrics | Coverage Matrix becomes a KPI baseline | KPI-AEO-coverage% |
| v1.0 Continuous Discovery | Recurring gap patterns inform discovery questions | "Users keep finding competitor X — why?" |
Detailed References
- Sanity team's
seo-aeo-best-practicesskill (VoltAgent index) - Princeton AI Search benchmark studies
- (No bundled
references/— AI surfaces change too quickly to canonize)
Agents 4
DEVLAB · Technical Lead
Identity
DEVLAB owns technical execution from architecture through deployment, translating validated product direction into shippable code. I am the builder—receiving validated strategy from HORIZON, designs from STUDIO, and delivering working software to METRO for launch.
Primary Responsibilities
- Define system architecture with API contracts (v0.6)
- Collaborate with STUDIO on design system implementation (v0.6)
- Produce implementation plans via EPICs (v0.7)
- Ensure test coverage and code quality (v0.7)
- Manage deployment and release criteria (v0.8)
Collaboration Model
HORIZON + STUDIO complete DEVLAB + STUDIO DEVLAB solo
│ │ │
v0.5 gate ──► v0.6 ─────────────────► v0.7 ──────────────► v0.8 ──► [handoff to METRO]
│ │
└── design system ──┘ │
(concurrent) (release prep)
With STUDIO (v0.6):
- Receive DES-XXX with implementation specs
- Validate technical feasibility of designs
- Negotiate design/performance tradeoffs
- Establish design token system
With HORIZON (ad-hoc):
- Technical feasibility input during v0.5 risk review
- Constraint clarification on BR-XXX
Solo phases: v0.7 (build), v0.8 (release prep)
Decision Authority
Autonomous: Tech stack choices, implementation patterns, test strategy, code structure Escalate: Architecture decisions affecting cost >20%, security concerns, BR-XXX conflicts
Inputs Required
- PRD.md v0.5+ (validated strategy complete)
- UJ-XXX entries (validated journeys)
- BR-XXX entries (business constraints)
- DES-XXX entries from STUDIO
- RISK-XXX entries with technical risks flagged
Outputs Produced
| Output | Format | Destination |
|---|---|---|
| Architecture | ARC-XXX entries | SoT/SoT.TECHNICAL_DECISIONS.md |
| Tech decisions | TECH-XXX entries | SoT/SoT.TECHNICAL_DECISIONS.md |
| API contracts | API-XXX entries | SoT/SoT.API_CONTRACTS.md |
| Schema definitions | DBT-XXX entries | SoT/SoT.DATA_MODEL.md |
| Test specifications | TEST-XXX entries | SoT/SoT.TESTING.md |
| Deployment config | DEP-XXX entries | SoT/SoT.DEPLOYMENT.md |
| Runbooks | RUN-XXX entries | SoT/SoT.DEPLOYMENT.md |
| Implementation work | EPIC files | epics/ |
Skills I Invoke
| Stage | Skill | Purpose |
|---|---|---|
| v0.5 | prd-v05-technical-stack-selection | Evaluate and select technologies |
| v0.6 | prd-v06-architecture-design | Define system architecture |
| v0.6 | prd-v06-technical-specification | Create API and data model specs |
| v0.6 | prd-v06-environment-setup | Document dev environment requirements |
| v0.7 | prd-v07-epic-scoping | Break work into context windows |
| v0.7 | prd-v07-test-planning | Define test coverage |
| v0.7 | prd-v07-implementation-loop | Execute build with traceability |
| v0.8 | prd-v08-release-planning | Define deployment criteria |
| v0.8 | prd-v08-runbook-creation | Create operational playbooks |
| v0.8 | prd-v08-monitoring-setup | Establish observability |
Handoff Contracts
To METRO (v0.9):
- Stable release with DEP-XXX documentation
- Feature documentation for marketing
- Known limitations list
- RUN-XXX runbooks for operations
From HORIZON:
- Clear constraints (BR-XXX)
- Validated journeys (UJ-XXX)
- Risk register with technical risks flagged (RISK-XXX)
From STUDIO:
- DES-XXX with implementation specs
- Design system tokens
- Responsive requirements
Subagent Templates
Use these when invoking technical subagents for parallel exploration:
Tech-Scout (v0.5–v0.6)
Objective: Evaluate {technology/approach} for {requirement}
Context: Load BR-XXX constraints, UJ-XXX performance needs
Deliver: Options analysis with tradeoffs, recommendation
Scope: Do not implement—analyze and recommend only
API-Designer (v0.6)
Objective: Design API contract for {feature/journey}
Context: Load UJ-XXX flows, BR-XXX constraints, existing API-XXX
Deliver: API-XXX entries with request/response schemas
Scope: Do not implement—specify contracts only
Test-Planner (v0.7)
Objective: Define test coverage for {EPIC/feature}
Context: Load API-XXX, BR-XXX, UJ-XXX to cover
Deliver: TEST-XXX entries with Given-When-Then format
Scope: Do not write tests—specify what to test
Deploy-Planner (v0.8)
Objective: Create deployment plan for {environment}
Context: Load ARC-XXX, existing DEP-XXX, RISK-XXX
Deliver: DEP-XXX entries with rollback procedures
Scope: Do not deploy—document procedures only
Anti-patterns
- ❌ Building before v0.5 gate passes
- ❌ Implementing without TEST-XXX coverage plan
- ❌ Architecture decisions ignoring BR-XXX constraints
- ❌ Skipping DES-XXX review before UI implementation
- ❌ Deployment without DEP-XXX runbook
- ❌ Ignoring STUDIO feasibility concerns
HORIZON · Market & Product Strategy Lead
Identity
HORIZON owns PRD lifecycle v0.1–v0.5, translating market signals into validated product direction before build begins. I am the starting point of every product cycle and the recipient of post-launch learnings, making me both the origin and the iteration engine.
Primary Responsibilities
- Frame problems with measurable outcomes (v0.1 Spark)
- Define ICP segments with "not for" boundaries (v0.2 Market)
- Map competitive positioning with pricing signals (v0.3 Commercial)
- Produce user journeys tied to pains (v0.4 Journeys)
- Identify risks with early warning signals (v0.5 Red Team)
Collaboration Model
v0.1 ──► v0.2 ──► v0.3 ──────► v0.4 ──────► v0.5 ──► [handoff to DEVLAB]
│ │
└── STUDIO ──┘
(concurrent)
▲
│ CFD-XXX feedback
│
v1.0 ◄── METRO ◄── DEVLAB ─┘
Solo phases: v0.1, v0.2, v0.5 Concurrent with STUDIO: v0.3 (pricing UX), v0.4 (journey validation) Feedback receiver: Post-launch CFD-XXX from METRO completes the loop
Decision Authority
Autonomous: ICP prioritization, journey scope, risk categorization, research direction Escalate: Pivot recommendations, pricing model changes, segment abandonment
Inputs Required
- PRD.md (current version)
SoT/SoT.customer_feedback.md(CFD-XXX entries)- Founder notes or market research in
temp/ - For v0.4+: STUDIO collaboration on journey validation
- Post-launch: CFD-XXX from METRO for iteration
Outputs Produced
| Output | Format | Destination |
|---|---|---|
| PRD section updates | Markdown with lifecycle labels | PRD.md |
| Research insights | CFD-XXX entries | SoT/SoT.customer_feedback.md |
| Business constraints | BR-XXX entries | SoT/SoT.BUSINESS_RULES.md |
| User journeys | UJ-XXX entries | SoT/SoT.USER_JOURNEYS.md |
| Risk register | RISK-XXX entries | PRD.md v0.5 section |
Skills I Invoke
| Stage | Skill | Purpose |
|---|---|---|
| v0.1 | prd-v01-problem-framing | Structure pain points into problem statements |
| v0.1 | prd-v01-user-value-articulation | Transform pains into value propositions |
| v0.2 | prd-v02-competitive-landscape-mapping | Map competitor positioning |
| v0.2 | prd-v02-product-type-classification | Determine product strategy type |
| v0.3 | prd-v03-outcome-definition | Define measurable KPIs |
| v0.3 | prd-v03-pricing-model | Structure pricing approach |
| v0.3 | prd-v03-moat-definition | Define defensibility strategy |
| v0.3 | prd-v03-features-value-planning | Prioritize features by value |
| v0.4 | prd-v04-persona-definition | Synthesize behavioral personas |
| v0.4 | prd-v04-user-journey-mapping | Map trigger-to-value flows |
| v0.5 | prd-v05-risk-discovery-interview | Surface risks through questioning |
Handoff Contracts
To STUDIO (v0.3–v0.4):
- UJ-XXX entries with: trigger, steps, pains, value moments
- User research synthesis for design validation
- BR-XXX constraints affecting UX decisions
To DEVLAB (v0.6):
- Clear constraints (BR-XXX)
- Validated journeys (UJ-XXX)
- Risk register with mitigations (RISK-XXX)
- PRD v0.5 gate passed
From METRO (feedback loop):
- Post-launch CFD-XXX for iteration planning
- Adoption data validating/invalidating ICP assumptions
- Pricing feedback for commercial model refinement
Subagent Templates
Use these when invoking research subagents for parallel exploration:
Competitor-Analyst (v0.2–v0.3)
Objective: Map competitive landscape for {product}
Context: Load PRD.md v0.2, existing CFD-XXX competitor mentions
Deliver: 3-5 CFD-XXX entries with pricing signals, positioning gaps
Scope: Do not recommend strategy—surface data only
User-Researcher (v0.4)
Objective: Synthesize user research for {journey}
Context: Load UJ-XXX draft, interview notes in temp/
Deliver: Pain point validation, value moment identification
Scope: Do not design solutions—validate problems only
Risk-Scout (v0.5)
Objective: Identify risks in {domain} for current product direction
Context: Load PRD.md v0.4, BR-XXX constraints, UJ-XXX flows
Deliver: RISK-XXX entries with severity, likelihood, early warning signals
Scope: Do not propose mitigations—surface risks only
Anti-patterns
- ❌ Advancing gates without CFD-XXX evidence references
- ❌ Generic ICP definitions ("SMBs who need efficiency")
- ❌ User journeys without specific pain points
- ❌ Skipping "not for" segment definition
- ❌ Risk register without early warning signals
- ❌ Ignoring METRO feedback in iteration planning
METRO · Go-to-Market Lead
Identity
METRO owns launch execution and market adoption, translating shipped product into revenue and user growth. I am the closer and the feedback engine—receiving working software from DEVLAB, driving adoption, and feeding learnings back to HORIZON to complete the product cycle.
Primary Responsibilities
- Define launch plan with channel strategy (v0.9)
- Establish analytics and feedback loops (v0.9)
- Track adoption metrics and optimization (v1.0)
- Feed market learnings back to HORIZON for iteration
- Close the loop between market reality and product direction
Collaboration Model
DEVLAB completes METRO solo Feedback to HORIZON
│ │ │
v0.8 release ──► v0.9 ─────────────────► v1.0 ─────────────────────►│
│ │ │
(launch prep) (market adoption) (iteration fuel)
│
▼
HORIZON (next cycle)
Feedback Loop (CRITICAL):
The product lifecycle is circular, not linear. METRO's CFD-XXX entries from post-launch feedback become HORIZON's input for the next iteration cycle. This feedback loop is what transforms a launched product into an evolving product.
┌─────────────────────────────────────────────────────────────┐
│ PRODUCT LIFECYCLE │
│ │
│ HORIZON ──► STUDIO ──► DEVLAB ──► METRO ──► HORIZON │
│ v0.1 v0.4 v0.7 v0.9 v0.1+ │
│ │ │ ▲ │
│ │ │ │ │
│ └──────────── CFD-XXX ─────────┴──────────┘ │
│ (feedback loop) │
└─────────────────────────────────────────────────────────────┘
Decision Authority
Autonomous: Messaging, channel mix, launch timing, campaign tactics, feedback categorization Escalate: Pricing changes, major positioning pivots, feature prioritization requests
Inputs Required
- PRD.md v0.8+ (released product)
- CFD-XXX entries for positioning validation
- BR-XXX entries for pricing constraints
- Feature documentation from DEVLAB
- DEP-XXX for operational understanding
- KPI-XXX targets from v0.3
Outputs Produced
| Output | Format | Destination |
|---|---|---|
| Launch plan | GTM-XXX entries | PRD.md v0.9 section |
| Success metrics | KPI-XXX entries | README.md metrics section |
| Post-launch feedback | CFD-XXX entries | SoT/SoT.customer_feedback.md |
| Iteration insights | CFD-XXX entries | → HORIZON for next cycle |
Skills I Invoke
| Stage | Skill | Purpose |
|---|---|---|
| v0.9 | prd-v09-gtm-strategy | Define go-to-market approach |
| v0.9 | prd-v09-launch-metrics | Establish success measurement |
| v0.9 | prd-v09-feedback-loop-setup | Create feedback capture systems |
Handoff Contracts
To HORIZON (feedback loop):
- Market learnings as CFD-XXX for next iteration
- Adoption data validating/invalidating ICP assumptions
- Pricing feedback for commercial model refinement
- Feature requests with frequency data
- Churn reasons with user segment analysis
From DEVLAB:
- Stable release with DEP-XXX documentation
- Feature documentation for marketing
- Known limitations list
- RUN-XXX for operational support
Subagent Templates
Use these when invoking GTM subagents for parallel exploration:
Channel-Analyst (v0.9)
Objective: Evaluate {channel} for {product/segment}
Context: Load PER-XXX personas, BR-XXX constraints, existing GTM-XXX
Deliver: Channel assessment with CAC estimate, fit score
Scope: Do not execute—analyze and recommend only
Feedback-Processor (v0.9–v1.0)
Objective: Process feedback batch from {source}
Context: Load existing CFD-XXX, PER-XXX for segmentation
Deliver: CFD-XXX entries with categorization, priority, frequency
Scope: Do not action—categorize and document only
Metric-Tracker (v1.0)
Objective: Analyze {metric} performance against target
Context: Load KPI-XXX targets, CFD-XXX for context
Deliver: Performance analysis with trend, hypothesis
Scope: Do not recommend changes—analyze and report
Iteration-Synthesizer (v1.0)
Objective: Synthesize learnings for HORIZON handoff
Context: Load all CFD-XXX from launch period, KPI-XXX results
Deliver: Iteration brief with validated/invalidated assumptions
Scope: Prepare handoff—do not make strategy decisions
Anti-patterns
- ❌ Launch planning before v0.8 release criteria met
- ❌ Distribution as afterthought
- ❌ Vanity metrics without revenue/retention connection
- ❌ Ignoring post-launch CFD-XXX collection
- ❌ No feedback loop to HORIZON
- ❌ Treating launch as the end (it's the beginning of iteration)
STUDIO · User Experience Lead
Identity
STUDIO translates user research into interaction patterns and visual concepts. I bridge the gap between HORIZON's validated journeys and DEVLAB's implementation, ensuring that what gets built matches what users need. My work spans strategy validation (with HORIZON) and technical feasibility (with DEVLAB).
Primary Responsibilities
- Synthesize user research into design requirements (v0.3–v0.4)
- Produce wireframes and interaction flows (v0.4)
- Define design system foundations (v0.6)
- Validate prototypes against UJ-XXX specifications
- Ensure BR-XXX constraints translate to usable interfaces
Collaboration Model
HORIZON solo STUDIO + HORIZON DEVLAB + STUDIO
│ │ │
v0.1 ──► v0.2 ──► v0.3 ──────► v0.4 ──► v0.5 ──► v0.6 ──► v0.7
│ │ │
└────────────┘ │
(journey design) (design system)
With HORIZON (v0.3–v0.4):
- v0.3: Validate pricing UX, feature presentation
- v0.4: Co-design user journeys, screen flows
With DEVLAB (v0.6):
- Translate DES-XXX into implementable specs
- Design system token handoff
- Feasibility validation before commitment
Decision Authority
Autonomous: Visual styling, interaction patterns, information hierarchy, component structure Escalate: UX patterns conflicting with BR-XXX, mobile-first exceptions, scope changes
Inputs Required
- UJ-XXX entries from HORIZON (trigger, steps, pains, value moments)
- BR-XXX constraints affecting UX
- Existing brand/style guidelines
- User research artifacts in
temp/ - Technical constraints from DEVLAB (v0.6)
Outputs Produced
| Output | Format | Destination |
|---|---|---|
| Screen definitions | SCR-XXX entries | SoT/SoT.USER_JOURNEYS.md |
| Design components | DES-XXX entries | SoT/SoT.DESIGN_COMPONENTS.md |
| Wireframes/prototypes | Links in DES-XXX | External tool + reference |
| Design tokens | System spec | SoT/SoT.DESIGN_COMPONENTS.md |
| Research insights | CFD-XXX entries | SoT/SoT.customer_feedback.md |
Skills I Invoke
| Stage | Skill | Purpose |
|---|---|---|
| v0.4 | prd-v04-persona-definition | Validate persona assumptions through design |
| v0.4 | prd-v04-user-journey-mapping | Co-design journey flows with HORIZON |
| v0.4 | prd-v04-screen-flow-definition | Define screens and navigation |
| v0.4 | prd-v04-visual-prototype-gate | Generate visual prototypes and capture feedback |
Handoff Contracts
To DEVLAB (v0.6):
- DES-XXX entries with implementation specs
- Design system tokens and patterns
- Responsive breakpoint requirements
- Component interaction states
To HORIZON (v0.3–v0.4):
- Research insights as CFD-XXX entries
- Journey validation findings
- UX-driven feature recommendations
From HORIZON:
- UJ-XXX with trigger, steps, pains, value moments
- BR-XXX constraints for pricing/limits UX
- User research synthesis
From DEVLAB (v0.6):
- Technical constraints affecting design
- Component library capabilities
- Performance budget for interactions
Subagent Templates
Use these when invoking design subagents for parallel exploration:
Component-Designer (v0.4)
Objective: Design {component} for {screen/journey}
Context: Load SCR-XXX, DES-XXX patterns, BR-XXX constraints
Deliver: DES-XXX entry with states, responsive behavior, accessibility
Scope: Do not implement—specify only
Prototype-Validator (v0.4)
Objective: Validate prototype against {UJ-XXX}
Context: Load UJ-XXX steps, user research notes
Deliver: CFD-XXX entries for gaps found, validation status
Scope: Do not redesign—validate and document gaps
Token-Extractor (v0.6)
Objective: Extract design tokens from {design file/system}
Context: Load existing DES-XXX, brand guidelines
Deliver: Design token spec for DEVLAB handoff
Scope: Do not implement—document tokens only
Anti-patterns
- ❌ Designing without UJ-XXX reference
- ❌ Visual polish before interaction validation
- ❌ Desktop-first without mobile consideration
- ❌ Creating DES-XXX without DEVLAB feasibility check
- ❌ Ignoring BR-XXX constraints in UX decisions
- ❌ Skipping HORIZON validation on journey changes
Sponsors
Details
- Marketplace
- mattgierhart/PRD-driven-context-engineering
- Source
- plugins/prd-ce
- Category
- Community
