PRD-CE methodology engine: scaffold (PRD/SoT/EPICs) + lifecycle skills + governance hooks + readiness scoring.

GitHub stars
179

Install

/plugin install prd-ce@prd-ce-methodology

Run it inside Claude Code after adding the marketplace with /plugin marketplace add mattgierhart/PRD-driven-context-engineering.

Contents

Discovered from source

Skills 50

[Skill Name]

[One sentence summary of the skill's purpose.]

Workflow Overview

  1. Step 1 → Brief description
  2. Step 2 → Brief description
  3. Step 3 → Brief description

Core Output Template

[Define the primary output structure this skill produces]

ElementDefinitionEvidence
Field 1What this capturesHow to validate
Field 2What this capturesHow 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. See PRINCIPLES.md P7.

Anti-Patterns

PatternExampleFix
Bad pattern 1"Example"→ "Better approach"
Bad pattern 2"Example"→ "Better approach"
Evidence fabricationBack-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

  1. Compute → run scripts/readiness.py run --quiet to refresh status/readiness.json
  2. Read → parse status/readiness.json
  3. Report → PASS / WARN / BLOCK verdict with top blockers and causal links
  4. 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 score
  • summary.top_blockers — ranked SoT files blocking progress
  • stages.{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 scoreVerdictMeaning
≥ 70PASSSafe to advance
50–69WARNAdvance with documented risk; log in PRD change log
< 50BLOCKCannot 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

PatternExampleFix
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 criteriaRe-checking IDs manuallyTrust the scorer; if wrong, fix GATE_REQUIREMENTS in _readiness/stage.py
Forcing PASSOverriding the verdictNever 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_blockers leverage view

DON'T:

  • Modify status/readiness.json directly — 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 rule
  • docs/READINESS_PROTOCOL.md — full schema

Harvest

Extract durable insights from temporary files to Source of Truth during EPIC Phase E (Finish).

Workflow Overview

  1. Enumerate Temps → List all temp/ files from current EPIC
  2. Identify SoT-worthy → Determine what should persist
  3. Format Entries → Convert to proper SoT templates
  4. Archive → Move temps to archive, update manifest

Core Output Template

ElementDefinitionEvidence
Temp FilesFiles processedList with paths
New SoT EntriesIDs createdBR-XXX, UJ-XXX, etc.
Archive ManifestWhat was archivedPaths and dates
DiscardedWhat was not keptReason for each

Harvest Decision Matrix

Content TypeActionDestination
Business rule discoveredExtractSoT/SoT.BUSINESS_RULES.md
User flow documentedExtractSoT/SoT.USER_JOURNEYS.md
API design finalizedExtractSoT/SoT.API_CONTRACTS.md
Customer feedback capturedExtractSoT/SoT.customer_feedback.md
Session notesArchive onlyarchive/YYYY-MM/
Scratch workDiscardDelete after review

Step 1: Enumerate Temp Files

  1. Read EPIC Execution Plan for temp file references
  2. List all files in temp/ directory
  3. 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:

QuestionIf YesIf No
Is this a business rule?Extract as BR-XXXContinue
Is this a user flow?Extract as UJ-XXXContinue
Is this an API design?Extract as API-XXXContinue
Is this customer evidence?Extract as CFD-XXXContinue
Is this useful context?ArchiveContinue
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:

  1. Generate appropriate ID using ghm-id-register
  2. Format per SoT template
  3. Add cross-references
  4. 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

  1. Create archive directory: archive/YYYY-MM/
  2. Move processed temps to archive
  3. Generate manifest
  4. 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

PatternExampleFix
Orphan tempsTemps not in manifest→ Process all files
Lost contextArchive without manifest→ Always create manifest
Over-extractionEverything becomes SoT→ Apply decision matrix
Under-extractionValuable 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

  1. Validate Format → Check ID follows [PREFIX]-[3-digit] pattern
  2. Check Uniqueness → Ensure ID doesn't already exist
  3. Verify Cross-Refs → All referenced IDs must exist
  4. Register Entry → Add to appropriate SoT file

Core Output Template

ElementDefinitionEvidence
IDUnique identifierBR-101, UJ-045, API-012
TitleShort descriptive nameClear, specific
Cross-ReferencesLinks to related IDsAll referenced IDs exist
StatusCurrent stateDraft / Active / Deprecated

ID Format Reference

PrefixDomainFile
BR-Business RulesSoT/SoT.BUSINESS_RULES.md
UJ-User JourneysSoT/SoT.USER_JOURNEYS.md
API-API ContractsSoT/SoT.API_CONTRACTS.md
CFD-Customer FeedbackSoT/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

  1. Read target SoT file
  2. Extract all existing IDs of same prefix
  3. Verify new ID doesn't exist
  4. 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:

  1. Identify the prefix
  2. Check that ID exists in its SoT file
  3. Flag any missing references

Checklist

  • All BR-XXX references exist in BUSINESS_RULES
  • All UJ-XXX references exist in USER_JOURNEYS
  • All API-XXX references exist in API_CONTRACTS
  • All CFD-XXX references 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:

ScoreEvidence LevelExamples
1/5Assumption / PM decision"We think users want X"
2/5Secondary researchCompetitive analysis, market report
3/5Direct feedbackUser interviews (3-5 conversations)
4/5Validated behaviorBeta testing, small-scale usage
5/5Production evidenceReal 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-analysis
  • confidence: 3/5, source: 5-user-interviews-jan-2026
  • confidence: 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

PatternExampleFix
Duplicate IDCreating BR-101 when it exists→ Check uniqueness first
Orphan referenceReferences UJ-999 that doesn't exist→ Verify all cross-refs
Wrong prefixUsing BR- for an API contract→ Match prefix to domain
Missing zero-padBR-5 instead of BR-005→ Always use 3 digits
Inflated confidenceAssigning 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 targetConfidence 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.sh is the deterministic CLI path. Both read .claude/install-manifest.yaml, so they can't drift. Prefer driving install.sh from this skill; fall back to manual copies only when the script isn't reachable.

Consumes

  • .claude/install-manifest.yaml — authoritative framework / template_seed / never_touch lists (the keystone; never hardcode file lists).
  • install.sh — the deterministic installer this skill normally drives.
  • Safety rules from ghm-template-sync Phase "Safety Rules" — never overwrite MEMORY.md, SoT/*, PRD.md, README.md content.

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.py runs).

Workflow

Phase 1 — Preflight & mode detect

  1. Confirm git, python3, awk are present; warn if the target isn't a git repo.
  2. Detect mode: greenfield (no .claude/) vs brownfield (existing .claude/). Brownfield means merge, never overwrite product.
  3. 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-run plan first [standard+], then execute.
  • If a framework file shows drift, surface the diff and only re-run with --force after the user confirms (mirrors ghm-template-sync "show diff before destructive").
  • Never write anything in the manifest's never_touch list.

Phase 4 — Verify (trust-but-verify, the Xantham verify-blueprint.sh analog)

  1. Run each .claude/hooks/*.sh in the target; assert valid JSON on stdout.
  2. 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.
  3. Print next steps: customize README.md + PRD.md, then "Let's frame the problem".

Anti-patterns

PatternFix
Hardcoding the file list in the skillRead .claude/install-manifest.yaml
Overwriting a brownfield repo's PRD.md/SoTHonor never_touch; seed templates once
Treating readiness BLOCK on a fresh scaffold as a bugIt's the gate working — report the score
Re-implementing copy logic instead of driving install.shOne 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

  1. Identify Need → Confirm no existing SoT fits
  2. Design Schema → Define ID prefix, categories, required fields
  3. Draft Template → Create pure structure (no methodology teaching)
  4. Validate Purity → Apply the litmus test
  5. Register & Integrate → Update SoT.README.md and ID system

Core Output Template

See assets/sot-template.md for the copy-paste starter template.

ElementDefinitionRequired
YAML Frontmatterversion, purpose, id_prefix, authorityYes
Purpose BlockSingle paragraph explaining what this tracksYes
Navigation SectionCategory links for quick accessYes
Entry TemplateRepeatable structure for each IDYes
Cross-Reference IndexBidirectional links to other SoT filesYes
Update ProtocolWhen/how to add new entriesYes

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

  1. What artifact type does this track?

    • Bad: "Notes" (too generic)
    • Good: "Partner Integration Contracts" (specific, durable)
  2. 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)
  3. What ID prefix will you use?

    • Must be unique across the system
    • 2-4 uppercase letters
    • Check SoT/SoT.UNIQUE_ID_SYSTEM.md for 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:

FieldPurposeExample
IDUnique identifierPIC-001
TitleHuman-readable name"Stripe Payment Integration"
StatusCurrent stateActive / Deprecated / Planned
CreatedOrigin date2025-01-10
Last UpdatedLast modification2025-01-15
Related IDsCross-referencesBR-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

  1. YAML Frontmatter - Metadata for the file
  2. Title & Purpose Block - What this SoT tracks
  3. Navigation by Category - Quick links to entries
  4. Entry Template - Repeatable structure (copy for each new entry)
  5. Deprecated Section - Where old entries go
  6. Cross-Reference Index - Bidirectional links
  7. 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

PatternExampleFix
Methodology in template"Best practices for partner selection"Move to skill references
Duplicate prefixUsing BR- for a new fileChoose unique prefix
Too generic"Notes.md"Be specific: "Partner_Integrations.md"
No update protocolTemplate with no maintenance sectionAdd "Update Protocol" section
Orphan SoTNot registered in SoT.README.mdAlways register new files

Bundled Resources

  • references/sot-patterns.md — Common patterns across existing SoT files
  • references/examples.md — Before/after examples of SoT creation
  • assets/sot-template.md — Copy-paste starter template

Handoff

After creating a new SoT:

  1. SoT file exists at SoT/SoT.{NAME}.md
  2. SoT.README.md lists the new file
  3. SoT.UNIQUE_ID_SYSTEM.md has the new prefix
  4. Ready to use ghm-id-register for adding entries

Status Sync

Synchronize the README.md Command Center with the current project state after gate advancement or EPIC status changes.

Workflow Overview

  1. Load Context → Read README.md, PRD.md metadata, Active EPIC Session State section
  2. Extract State → Pull lifecycle stage, blockers, metrics
  3. Update Dashboard → Sync README sections with current truth

Core Output Template

ElementDefinitionEvidence
Lifecycle StageCurrent PRD version from PRD.mdCurrent Lifecycle Gate: v0.X
Gate StatusVisual progress indicators🟢 Complete / 🟡 In Progress / ⚪ Pending
Active EPICCurrent work from EPIC headerEPIC-XX: Title
BlockersOpen blockers from EPIC Session State sectionList with severity

Step 1: Load Context

Read these files in order:

  1. README.md (current state)
  2. PRD.md (metadata block for lifecycle stage)
  3. 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:

FieldSource
Lifecycle StagePRD.md Current Lifecycle Gate
Gate ProgressPRD.md gate table
Active EPICREADME.md Active Work section
BlockersEPIC Session State section
MetricsREADME.md Truth Table

Step 3: Update README Dashboard

Apply synchronization rules:

  1. Lifecycle Stage: Update header to match PRD.md
  2. Gate Table:
    • 🟢 = Passed gates (all criteria met)
    • 🟡 = Current gate (in progress)
    • ⚪ = Future gates (not started)
  3. Active EPIC: Update metadata in Active Work section
  4. Blockers: Sync from EPIC Session State section
  5. 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)

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

PatternExampleFix
Stale gate status🟢 on gate with missing criteria→ Verify all criteria before marking complete
Missing blockersEPIC has blockers, README shows none→ Always sync from EPIC Session State section
Wrong EPIC referenceREADME 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

  1. Read .claude/VERSION (if it exists) to get current template version
  2. If no VERSION file, check CLAUDE.md frontmatter for template_version
  3. If neither exists, assume v1.0.0 (pre-versioning)
  4. 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.sh
  • CHANGELOG.md
  • MIGRATION.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 with AGENT.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:

FileStatusActionRisk
.claude/VERSIONMissingCopy from templateNone
.claude/hooks/*.pyStaleDelete (replaced by .sh)None
.claude/agents/HORIZON.mdStaleSplit into horizon/AGENT.md + MEMORY.mdPreserve MEMORY.md content
settings.jsonOutdatedUpdate hook nesting + commandsCheck for custom hooks
CLAUDE.mdMissing frontmatterAdd template_version: "3.0.0"None

Phase 4: Execute Safe Updates

Auto-safe (do without asking):

  • Create .claude/VERSION with current template version
  • Add template_version frontmatter to files that lack it
  • Report what was done

Confirm first (show diff, ask user):

  • Update settings.json hook configuration
  • Restructure agent files (must preserve MEMORY.md)
  • Delete stale Python hooks
  • Update EPIC template headers

Never touch (product-specific):

  • PRD.md content (only add frontmatter)
  • SoT/*.md content
  • epics/EPIC-*.md content (only update headers on closed EPICs)
  • .claude/agents/*/MEMORY.md content
  • README.md content

Phase 5: Verify

After all changes:

  1. Test all shell hooks produce valid JSON
  2. Verify no Python hooks remain
  3. Confirm settings.json uses correct nesting
  4. Check agent subdirectories have both AGENT.md and MEMORY.md
  5. Report summary of changes made

Version Migration Matrix

FromToKey Changes
v1.0.0v2.0.0Add skills, hooks, agents, SoT standardization
v2.0.0v3.0.0Shell hooks, agent subdirs, semantic EPICs, versioning, domain-profile
v1.0.0v3.0.0All of the above (cumulative)

Safety Rules

  1. NEVER overwrite MEMORY.md -- these contain product-specific agent memory
  2. NEVER modify SoT content -- only add section markers or frontmatter
  3. NEVER modify PRD.md content -- only add frontmatter version
  4. ALWAYS show diff before destructive changes (deletes, restructures)
  5. ALWAYS verify hooks work after updating settings.json
  6. 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's template_seed section — the same list install.sh (fork path) and ghm-template-sync (update path) read. This skill drives the deterministic prd-ce-init.sh so 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 has PRD.md or SoT/ content, the seeder keeps it (non-destructive) rather than adapting to it.

Consumes

  • ${CLAUDE_PLUGIN_ROOT}/templates/ — the bundled seed sources (mirrors template_seed paths) the packager ships with the plugin.
  • install-manifest.yaml template_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 stale template_version).
  • A verification report (hooks emit valid JSON; readiness.py runs).

Workflow

Phase 1 — Preflight

  1. Confirm git, python3, bash are present. Warn (don't block) if the target isn't a git repo.
  2. Confirm greenfield: if PRD.md or non-empty SoT/ 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-run plan first [standard+], then execute.
  • The seeder skips any file that already exists (never_touch honored) and resets a freshly seeded PRD.md frontmatter 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)

  1. Run each plugin hook against the target; assert valid JSON on stdout.
  2. 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.
  3. Print next steps: customize README.md + PRD.md, then "Let's frame the problem" (v0.1).

Anti-patterns

PatternFix
Hardcoding the seed file list in the skillDrive prd-ce-init.sh; it reads template_seed
Copying the framework (skills/hooks) into the consumer repoThe 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 headerFrontmatter reset to v0.1 happens automatically on a fresh seed
Treating a readiness BLOCK on a fresh scaffold as a bugIt'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

  1. Assess gaps → Identify what evidence is missing before you can confidently state a problem
  2. Anchor evidence → Create CFD- entries for each pain point dimension with confidence scoring
  3. Extract dimensions → Pull multiple distinct problems from each source
  4. Quantify costs → Add time/money/risk numbers to make pain concrete
  5. Draft statement → Populate the problem table, tied to CFD- entries

Core Output Template

Populate this table for every problem statement:

ElementDefinitionEvidence
Who is hurting?Specific, findable, countable personaSegment size
What pain exists?Observable behavior or workflow frictionCFD-ID
Cost of problemTime, money, or opportunity lostQuantified
Why now?Market trigger creating urgencyTrend/event
What's impossible?Opportunity cost—what can't they doUser quote

See assets/problem-statement.md for copy-paste template.

Step 1: Gap Assessment

Before drafting, create this status table:

ElementStatusSource
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:

TypeCalculation
TimeHours/week × hourly rate
MoneyCurrent spend on workaround
OpportunityRevenue/outcomes missed
RiskPenalty × 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

PatternExampleFix
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

  1. Receive pain points → Read CFD-IDs from Problem Framing
  2. Identify value unit → Time / Money / Risk / Capability
  3. Transform pain → value → Apply transformation pattern
  4. Anchor to evidence → What proof users want this outcome?
  5. Create CFD entry → Tag as value hypothesis with tier

Core Output Template

ElementDefinition
Pain (source)CFD-ID from Problem Framing
Value StatementOne sentence: what user gains
Value UnitTime / Money / Risk / Capability
QuantificationNumber with unit
Framing TypeNegative Removal / Positive Gain / Capability Unlock / Risk Reduction
Evidence Tier1-5 per hierarchy
Supporting CFDNew CFD-ID for value hypothesis

See assets/value-statement.md for copy-paste template.

Pain → Value Transformation

Pain PatternValue 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

TypeWhen to Use
Negative RemovalPain is acute, quantified loss; "hate", "wasting", "losing"
Positive GainOpportunity cost clear; "I wish I could..."
Capability UnlockSomething impossible, not just hard; "We can't..."
Risk ReductionRegulatory/compliance; penalty amounts cited

Value Evidence Tier Hierarchy

TierDescriptionWeight
1User already paying for this value elsewhere✅ Highest
2User actively trying to achieve this outcome✅ Strong
3User articulates wanting this (unprompted)✅ Acceptable
4User agrees when prompted⚠️ Weak
5Builder 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

PatternSignalFix
Feature as value"Dashboard", "tool", "feature" in statementRewrite as outcome
Unmeasurable"Better", "improved" without numberAdd quantity
DisconnectedPain unit ≠ value unitMatch units
Round inflation"Save 10 hours" no sourceRequire calculation
No evidenceNo CFD-ID for user desireDowngrade tier
Solution creepHOW (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

  1. Document current behavior → What users do TODAY (before competitor search)
  2. Discover alternatives → Direct, adjacent, workarounds, "do nothing"
  3. Analyze gaps → Industry/geography gaps, underserved segments
  4. Compare features → Build comparison matrix
  5. Form hypothesis → 1% better hypothesis with evidence

Core Output Template

ElementDefinitionEvidence
Current BehaviorHow users solve this todayObserved workflow
Direct CompetitorsProducts solving same problemRevenue/funding proof
Adjacent SolutionsProducts solving related problemsUser overlap
WorkaroundsDIY solutions (spreadsheets, manual)Forum/reddit mentions
Feature MatrixSide-by-side capability comparisonProduct documentation
Gap AnalysisWhere competition is weakReviews, complaints
1% HypothesisHow we winEvidence-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

CategoryDefinitionSearch Strategy
DirectSame problem, same segment"[problem] software"
AdjacentRelated problem, potential pivot"[related workflow] tool"
WorkaroundsDIY solutionsReddit: "how I [task]"
Do NothingAccept status quoWhy 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

IndustryCompetitors ServingGap Level
[Industry 1]X of YNone / Small / Large
[Industry 2]X of YNone / Small / Large

Segment Gap Table

SegmentServed ByUnderserved 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:

FeatureUs (Planned)Competitor ACompetitor BGap
[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

PatternSignalFix
Competitor-first thinkingStarted with competitor featuresDocument current behavior first
False uniqueness"No competitors" claimInclude workarounds and adjacent
Feature bloatMatrix has 20+ featuresFocus on differentiators
Vague gaps"Better UX" without evidenceAdd specific user complaint
10x claims"10x better than X"Start with 1% provable claim
Ignored workaroundsOnly listed software competitorsInclude 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

TypeDefinitionWhen Evidence Shows
CloneCopy proven product, execute betterLeader validated market; weak moat; execution gap
UnbundleExtract one category from horizontal platformMulti-category platform does your thing poorly
UndercutSame product, simpler + cheaper for nicheTool overserves broad market; 60%+ price gap possible
SlicePlugin/extension in existing ecosystemPlatform has marketplace; users already there
WrapperAI/API layer on existing data/toolsMiddleware gap between tools; data accessible
InnovationNew solution to known problemExisting 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

TypeRequired Evidence (from v0.2 Landscape)Confidence Threshold
CloneRevenue proof + feature gap + weak moatMedium (50%+)
UnbundlePlatform size + category neglect + user complaintsMedium (50%+)
UndercutPrice benchmarks + niche pain + simplification pathHigh (70%+)
SlicePlatform MAU + marketplace presence + integration docsHigh (70%+)
WrapperAPI availability + use case validation + cost modelHigh (70%+)
InnovationFailed alternatives + severe pain + budget evidenceVery 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

  1. Claiming Innovation when it's really Clone: If competitor exists with revenue, you're not innovating
  2. Undercut without price evidence: Must show 60%+ reduction is possible AND sustainable
  3. Slice without ecosystem validation: Platform must actually want third-party apps
  4. Wrapper without API access confirmed: Technical feasibility must precede classification
  5. Unbundle from small platform: Only works against large horizontal players

Reference Files

  • Decision Framework: See references/decision-framework.md for expanded decision trees
  • Examples: See references/examples.md for good/bad classification cases
  • GTM Constraints: See references/gtm-constraints.md for type → constraint mapping
  • Classification Template: See assets/classification.md for 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

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

TypeDefinitionStrategic PurposeEvidence Required
MoatBuilds/defends competitive advantageSupports BR- moat ruleHigh (CFD- proving differentiation)
OutcomeDirectly drives success metricTied to KPI- entryHigh (KPI- link mandatory)
ParityMatches competitor baselineFrom Competitive LandscapeMedium (CFD- competitor evidence)
DeltaDifferentiation from competitorsOur advantage over marketHigh (CFD- gap evidence)
TierDifferentiates pricing packagesFrom Pricing BR-Medium (BR- tier assignment)
Table StakesExpected but not differentiatingIndustry standardLow (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 TypePrimary FocusParity ApproachDelta Approach
Fast FollowParity + focused delta1:1 critical feature matchSingle compelling improvement
InnovationMoat-building featuresMinimal (new category)Core differentiation IS the product
SliceSegment-specific featuresPartial (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

TierCriteriaEvidence Threshold
P0 — Must HaveBlocks launch without it; tied to primary KPI- or moat BR-CFD- proof + KPI-/BR- link
P1 — Should HaveMeaningfully improves outcome; supports tier differentiationCFD- user signal
P2 — Nice to HaveEnhances experience; no direct KPI impactReasonable assumption OK
P3 — Defer/CutScope creep signal; can add post-launchNone (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- entry
  • BR-FEA-002: Validation Before Build — P0 features require CFD- evidence before development
  • BR-FEA-003: Scope Freeze Gate — Feature list locked after v0.4; changes require EPIC

Anti-Patterns to Avoid

Anti-PatternSignalFix
Feature creepP2/P3 > 40% of scopeCut ruthlessly; defer to backlog
Implementation masquerading as feature"Use Redis caching"Reframe as user outcome
Orphaned featuresNo KPI-, BR-, or CFD- linkAdd traceability or cut
Assumption-based priority"Users will love this"Require CFD- evidence
Parity inflationEverything is "parity"Challenge: is competitor feature actually used?
Delta without moatDelta feature easy to copyTie to defensible BR- moat

Downstream Connections

This skill's outputs feed into multiple downstream skills:

ConsumerConsumesPurpose
v0.4 User JourneysFEA-* entries + MVP-SCOPE artifactDesign journey paths through MVP features
v0.5 Red Team ReviewFEA-* entriesAssess technical/risk feasibility of features
v0.6 ArchitectureFEA-* entries + MVP-SCOPEDesign system that supports MVP features
v0.7 Build ExecutionFEA-* entries + MVP-SCOPEDefine EPIC scope (which features = which EPICs)
v0.9 GTMFEA-* 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 TypeDefinitionStrong WhenWeak When
Switching CostsFriction to leave (data, workflow, contracts)Multi-year data, deep integrationsEasy export, monthly contracts
Network EffectsValue increases with usersTwo-sided marketplace, content platformSingle-player tool, linear value
Data/IPProprietary data or algorithmsUnique training data, patentsCommodity ML, public datasets
Brand/TrustRecognition, credibilityRegulated industry, high-risk decisionsLow-stakes, undifferentiated
Scale/CostVolume economicsInfrastructure-heavy, marginal cost near zeroLabor-intensive, linear cost
RegulatoryCompliance barriersCertifications required, government contractsNo 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:

TierCriteriaEvidence SignalsTargeting Implication
ImpenetrableMulti-layered moat, 10+ years data lock-in"Would take years to switch"Avoid direct competition
StrongSignificant switching friction, 1-2 year contractsHigh NPS + low churn despite complaintsTarget underserved segments only
ModerateSome friction, workarounds existChurn 5-10%, export optionsWedge opportunity exists
WeakEasy to replace, commodity offeringMonthly plans, high churn, price shoppingDirect competition viable
ErodingFormer strength decliningNew alternatives gaining shareAggressive 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 TypeHigh ImpactLow ImpactHow to Assess
Financial>6mo contract, early termination feesMonthly billing, no penaltyCheck pricing page terms
Time/Effort40+ hr migration, retraining<4 hr setup, familiar UXTrial the competitor
Data MigrationProprietary format, no exportStandard export (CSV, API)Test export function
Workflow RetrainingUnique methodology, team habitsStandard patternsRead onboarding docs
Integration ReworkDeep API dependenciesStandalone toolMap 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'tDo Instead
"They're big"Specify which moat type + evidence
Assume low switching costQuantify: hours + dollars
Only analyze direct competitorsInclude Type 4-5 (workarounds, inertia)
Underestimate integration moatMap actual dependency depth
Ignore eroding moatsTrack signals: new entrants, complaints
Target where moat is strongFind 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

ConsumerWhat It NeedsFormat
v0.3 Our Moat ArticulationWhere competitors are weak, what moats workCFD-MOT entries
v0.3 Pricing ModelWhat price points bypass switching frictionBR-TGT entries
v0.5 Red TeamRisks of competitor responseMoat strength tiers
v0.9 GTMPositioning against competitor moatsTargeting 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:

TierMetric TypesWhy It Matters
Tier 1Revenue (MRR, first dollar, ACV), Churn (logo, NRR), LTV:CACRevenue validates market fit. "First dollar IS the proof."
Tier 2Conversion rates (trial→paid, lead→customer), Time to Value, ActivationLeading indicators that predict Tier 1 outcomes
Tier 3Engagement (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 TypePrimary MetricsAnti-Metrics (Avoid)
CloneFeature parity score, Price delta vs. leader, TTFV vs. leaderGeneric engagement (doesn't prove you beat leader)
UndercutPrice per [unit] vs. leader, Niche conversion rate, CAC in target segmentBroad market share (you're niche by design)
UnbundleCategory NPS vs. platform, Vertical retention, Feature depth usagePlatform-level metrics (irrelevant to your slice)
SliceMarketplace ranking, Install→activate rate, Platform retention liftTAM metrics (platform owns the market)
WrapperTime saved per workflow, API reliability, Integration adoptionStandalone usage (value is in connection)
InnovationEducation→activation conversion, Behavioral change rate, Reference customersUser 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

  1. Vanity metrics as primary: "50K users" means nothing if only 500 pay
  2. Traffic without quality: High volume + low engagement = quality problem
  3. Arbitrary targets: "10% improvement" without baseline or benchmark
  4. All lagging, no leading: Can't course-correct if you only see outcomes monthly
  5. Ignoring product type: Clone metrics ≠ Innovation metrics
  6. Unmeasurable outcomes: "Better experience" — how do you know?

Downstream Connections

KPI- entries feed into:

ConsumerWhat It UsesExample
v0.5 Red TeamKill thresholds"If KPI-001 not hit by Day 21, pivot"
v0.7 Build ExecutionEPIC acceptance criteria"EPIC complete when KPI-002 validated"
v0.9 GTMLaunch dashboardTrack KPI-001, KPI-003 post-launch
BR- Business RulesDerived 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 TypeTypical ModelWhy It FitsAnti-Model (Avoid)
Fast FollowMatch market structureUsers expect familiar pricingPremium positioning (no differentiation)
UndercutFlat rate, aggressive discountPrice IS the value propPer-user (negates savings)
CloneParity or slight discountMust compete on terms users knowInnovation pricing (confuses buyers)
SliceUsage-based or ecosystem-tiedValue tied to platform activityFlat fee (misaligned with usage)
WrapperPer-integration or usageValue = connections madePer-seat (value isn't user count)
InnovationValue-based, potentially premiumFunds education, signals qualityRace to bottom (devalues category)

Value Timing → Model Selection

Ask: When does the customer get value?

Value PatternRecommended ModelExamples
Continuous recurringSubscription (monthly/annual)SaaS tools used daily
Per-transactionUsage-basedAPI calls, exports, generations
One-time outcomeOne-time fee or lifetimeLogo design, course completion
Milestone-basedTiered + upsell triggersFeatures 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

TierMethodConfidenceWhen to Use
1 (Highest)Actual purchase, payment collected95%+Post-MVP, real customers
2Pre-order, payment intent, trial→paid70-85%Landing page tests
3Email signup at stated price50-65%Smoke tests
4Survey, 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:

PurposeFree Tier DesignExample
Viral acquisitionGenerous + sharing incentiveDropbox referral
Product-led growthUseful enough to hook, limited enough to upgradeNotion personal
Market educationDemo the category valueNew category tools
Usage seedingGet data/content, charge for outputCanva 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:

TierPurposeDesign Principle
Free/TrialHook and demonstrate valueFirst win in <5 minutes
Entry/StarterConvert to payingLowest price that sustains business
Pro/GrowthCapture value from power usersFeatures that scale with success
EnterpriseCustom needs, high touchSLAs, 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

PrefixCategoryExample Rules
BR-PRC-Price constraintsPrice floor, ceiling, discount cap
BR-PKG-Packaging rulesTier boundaries, feature gates
BR-CMP-Competitive positioningAnchor 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'tDo Instead
Copy competitor pricing blindlyUnderstand their value timing and cost structure
Innovation product at Fast Follow pricePrice for value, not market incumbents
Free tier without upgrade triggerDefine clear conversion moment
Discount to win dealsMaintain price integrity, add value
Change pricing weeklySet, validate, iterate quarterly
Gut-feel price pointsWTP validation (Tier 1-2 evidence)

Validation Workflow

Before locking pricing:

  1. Calculate cost floor: What's minimum price for positive unit economics?
  2. Identify anchor: What do customers pay today? (competitor or workaround)
  3. Design tiers: Entry + Pro minimum; free only if strategic
  4. Test WTP: Landing page with price, measure signup conversion
  5. 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

ConsumerWhat It UsesExample
v0.3 Moat ArticulationPrice as moat element"Price leadership" defense
v0.5 Red TeamPricing risk assessment"What if competitor undercuts?"
v0.9 Unit EconomicsPrice inputs to CAC/LTVRevenue per customer calculation
GTM StrategyPricing 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

TypeDefinitionWhen to Create
PrimaryCore user, drives most revenueAlways (at least 1)
SecondaryImportant but not primary buyerIf distinct needs exist
NegativeWho we explicitly excludeIf exclusion is strategic
AspirationalFuture target, not current focusOnly 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 FieldMust Link ToSource Stage
GoalsCFD- value hypothesisv0.1 User Value Articulation
FrustrationsCFD- pain pointsv0.1 Problem Framing
Decision FactorsCFD- competitive researchv0.2 Competitive Landscape
Key FeaturesFEA- entriesv0.3 Feature Value Planning
Pricing SensitivityBR- pricing rulesv0.3 Pricing Model
Acquisition ChannelBR- targeting rulesv0.3 Moat Definition

No link = No claim. If you can't cite evidence, the attribute is assumption, not fact.

Synthesis Process

  1. Pull USER TYPE from v0.1 Problem Framing (CFD-)

    • These are your candidate personas
  2. Pull SEGMENTS from v0.2 Market Definition (CFD-, BR-)

    • How is the market divided? Which segments are we targeting?
  3. Pull TARGETING RULES from v0.3 Moat Definition (BR-)

    • New-to-category vs. Switchers? Trigger moments?
  4. Synthesize behavioral patterns from all CFD- evidence

    • What goals unite this segment?
    • What frustrations are consistent?
  5. Map FEA- features to each persona

    • Which features matter most to each?
    • This informs journey mapping
  6. 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-PatternSignalFix
Persona explosion>5 personasConsolidate by behavior, not demographics
Fictional personasNo CFD- linksEvery 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 competitorsGeneric descriptionsGround in YOUR research
Features without personasPersonas created but no FEA- linksMap 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:

ConsumerWhat It UsesExample
v0.4 User Journey MappingEach UJ- references a PER-UJ-001 is for PER-001
v0.4 Screen Flow DefinitionPersona context shapes UISCR-001 optimized for PER-001 tech level
v0.9 GTMMarketing messaging per personaCampaign targeting PER-002 segment
Sales EnablementPersona-specific pitchesDiscovery 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

TypeDefinitionDesign PriorityExample
PageFull viewport, primary navigation targetHighDashboard, Settings
ModalOverlay, blocks underlying pageMediumConfirmation, Quick Edit
PanelSlide-out, contextual detailMediumDetail View, Filters
ComponentReusable UI elementVariesHeader, Data Table

Rule: Start with Pages, then identify where Modals/Panels reduce navigation friction.

Navigation Patterns

Choose a pattern based on product type:

PatternWhen to UseExample Products
Hub & SpokeDashboard-centric appsAnalytics, CRM
Linear FlowWizard/checkout processesOnboarding, E-commerce
HierarchicalContent-heavy appsDocumentation, CMS
FlatSimple single-purpose appsTimer, Calculator

Most SaaS products use Hub & Spoke with occasional Linear Flows for onboarding/purchase.

Mapping Process

  1. Pull UJ- (journeys) and FEA- (features) from prior steps

    • Journeys define the paths; features define the capabilities
  2. Inventory unique screens needed across all journeys

    • Walk through each journey step and ask: "What screen does this happen on?"
  3. Map features to screens (many:many relationship)

    • One feature may appear on multiple screens
    • One screen may contain multiple features
  4. Define navigation structure

    • How do users get from screen to screen?
    • What's the hierarchy? What's always accessible?
  5. Identify shared components

    • Headers, footers, navigation bars
    • Common patterns: data tables, forms, cards
  6. Create SCR- entries with journey and feature traceability

  7. 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:

CategoryExamplesDesign Priority
Entry PointsLogin, Landing, SignupHigh (first impressions)
Core WorkflowMain task screensHigh (value delivery)
Settings/AdminPreferences, Account, BillingMedium (necessary)
Support/HelpDocs, Contact, FAQLow (failure recovery)

Rule: Invest design effort proportional to priority. Don't over-design settings screens.

Feature-to-Screen Matrix

Create a mapping matrix:

FeatureSCR-001SCR-002SCR-003SCR-004
FEA-001 (auto-sync)✓
FEA-003 (reports)PreviewFull
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-PatternSignalFix
Screen explosion>20 unique screens for MVPConsolidate; use modals/panels instead
Feature-per-screen1:1 FEA to SCR mappingGroup related features on screens
No shared componentsEvery screen is uniqueExtract DES- patterns
Navigation dead-endsCan't get back from a screenEnsure bidirectional paths
Journey disconnectSCR- not tied to UJ-Every screen serves a journey
Modal abuseEverything is a modalModals 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:

ConsumerWhat It UsesExample
v0.5 Technical Stack SelectionScreen complexity informs frontend needs"20 screens → need component library"
v0.6 Technical SpecificationScreens inform API data needsSCR-001 → API-001 (dashboard data)
v0.7 Build ExecutionScreens become implementation tasksEPIC-03 builds SCR-001–005
DesignSCR- entries become wireframes/mockupsSCR-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

TypePurposePriority SignalExample
CorePrimary value deliveryMust complete for activationFirst report generated
OnboardingFirst-time user setupBlocks all other journeysAccount creation → first action
RecoveryError handling, supportRetention protectionPassword reset, billing issue
Power UserAdvanced workflowsExpansion/upsellBulk operations, integrations

Rule: Define Onboarding first (it gates everything), then Core journeys (they deliver KPI-), then others.

Journey Anatomy

Every journey has:

  1. Trigger — What causes the user to start? (Event, not "opens app")
  2. Steps — Actions linked to FEA- features
  3. Pain Points — Where friction exists (design around these)
  4. Moment of Value — When user achieves goal (this drives KPI-)

Mapping Process

  1. Pull PER- (personas) from Persona Definition

    • Each journey belongs to a specific persona
  2. Pull FEA- (features) and KPI- (outcomes) from v0.3

    • Features are the building blocks of journey steps
    • KPIs tell you which journeys matter most
  3. Define trigger events

    • What causes the user to start this journey?
    • Be specific: "Receives calendar invite" not "opens app"
  4. Map step flow using features

    • Each step = an action the user takes
    • Link each step to the FEA- that enables it
  5. Identify pain points

    • Where might the user get confused, frustrated, or blocked?
    • These inform UX design decisions
  6. Mark "moments of value"

    • When does the user get the payoff?
    • This should tie to KPI- measurement
  7. 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:

  1. Add it to a journey (you missed a use case), or
  2. 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-PatternSignalFix
Feature-first journeysSteps = feature list dumped in orderStart with user goal, then map features to it
No trigger"User opens app"Define specific event: "receives notification"
No value momentJourney ends without payoffEach journey needs clear outcome
Orphaned featuresFEA- not in any journeyAdd to journey or cut from scope
Generic personas"User does X"Specify PER-: "PER-001 does X"
Happy path onlyNo pain points identifiedAnticipate where users struggle
Mega-journeys15+ stepsSplit 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:

ConsumerWhat It UsesExample
v0.4 Screen Flow DefinitionSteps become screensUJ-001 Step 3 → SCR-005
v0.6 Technical SpecificationJourneys inform API sequencesUJ-001 → API-001, API-002 flow
v0.7 Test PlanningJourneys become E2E testsTEST-020 validates UJ-001
v0.9 GTMJourney-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:

  1. Paste the Prototype Context Brief first
  2. Generate one screen at a time using per-screen prompts
  3. Refine each screen with targeted follow-ups ("Move the CTA to the right," "Change card layout to 2-column grid")
  4. 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

ConsumerWhat It Uses
v0.5 Red Team ReviewVisual prototype informs risk assessment — "does this feel buildable?"
v0.6 ArchitectureValidated screens inform API data requirements
v0.7 Build ExecutionPrototype becomes the visual spec for implementation
Stakeholder CommunicationMoney 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

  1. Interview, not inquisition — Facilitate discovery, don't interrogate
  2. Inform, not kill — Surface risks so user can mitigate, not abandon
  3. User owns decisions — AI facilitates, user assigns severity and response
  4. Actionable outputs — Every risk has a mitigation path or explicit "accept"

Risk Categories

Discovery Categories (Interview Prompts)

CategoryFocus AreaExample Questions
MarketCompetitors, timing, demand"What if [competitor] launches this feature next month?"
TechnicalComplexity, unknowns, dependencies"Which feature has the most technical uncertainty?"
AdoptionUser behavior, activation, retention"What's the biggest friction point in onboarding?"
ResourceTeam, budget, time"If you had to cut scope by 50%, what stays?"
DependencyExternal factors, integrations, partners"What external factor could block launch?"
TimingDeadlines, 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 CategoryDiscovery CategoriesMeasures
MarketMarket, TimingWill anyone buy this?
UserAdoption, DependencyWill users succeed with this?
TechnicalTechnical, ResourceCan 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

TechniqueHow to UseWhen 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

ResponseWhen to UseExample
MitigateCan reduce impact or likelihoodAdd fallback provider, implement retry logic
AcceptLow impact or unavoidable"Competitor might copy us—we accept"
AvoidChange plan to eliminate riskRemove feature with high technical uncertainty
TransferSomeone else owns the riskUse managed service instead of self-hosting

Severity Matrix

Low ImpactMedium ImpactHigh Impact
High LikelihoodMonitorMitigateMitigate urgently
Medium LikelihoodAcceptMonitor/MitigateMitigate
Low LikelihoodAcceptAccept/MonitorMonitor

Anti-Patterns to Avoid

Anti-PatternSignalFix
Risk theater50+ risks documentedFocus on top 10 that matter
All high severityEverything is criticalForce rank; max 3-5 "High"
No ownerRisks without accountabilityEvery RISK- needs an owner
Mitigation = "be careful"Vague responsesRequire specific, testable actions
Interview becomes lectureAI talks more than userAsk, listen, summarize
Killing ideasEvery risk leads to "don't do it"Frame as "how to succeed despite"

Phase 5: Score & Scorecard

After documenting all risks:

  1. Assign scoring categories: Map each RISK- to Market, User, or Technical
  2. Calculate scores: Raw Score = Impact × Likelihood; Effective = Raw × Status Weight (all start as open)
  3. Sum by category: Add effective scores within each scoring category
  4. Determine risk level: Total score → Low (0-12), Moderate (13-25), Elevated (26-40), High (41+)
  5. 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:

StageTypical New RisksScore Impact
v0.6 ArchitectureInfrastructure complexity, integration unknownsTechnical score rises
v0.7 BuildImplementation blockers, test coverage gapsTechnical score rises
v0.8 DeploymentOperational risks, security findingsTechnical score rises
v0.9 GTMMarket timing shifts, competitive movesMarket score rises
v1.0 GrowthReal adoption data contradicting assumptionsUser score rises

Protocol when adding risks after v0.5:

  1. Use the same RISK- template (assign next available number)
  2. Set Added: v0.X to record which stage surfaced it
  3. Recalculate category and total scores
  4. Update README Risk Scorecard

Protocol when risk status changes:

  1. Update the RISK- entry status in PRD.md
  2. Recalculate effective score (Raw × new Status Weight)
  3. Update README Risk Scorecard totals

Downstream Connections

RISK- entries feed into:

ConsumerWhat It UsesExample
README Risk ScorecardAggregated scores by categoryTotal score determines project risk level
v0.5 Technical Stack SelectionRISK- constraints affect tech choicesRISK-003 (latency) → choose edge hosting
v0.6 Architecture DesignRisk mitigations become architecture requirementsRISK-005 → add circuit breaker
v0.7 Build ExecutionRisk monitoring in EPICTrack RISK-001 early signals
KPI- ThresholdsKill 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

  1. Discover Existing Assets → Read SOT or interview user for current tech stack
  2. Categorize Layers → Reuse / Extend / New / Replace for each capability
  3. Evaluate Vendor Fit → Check vendor options for New/Replace layers (if constraints exist)
  4. Evaluate Alternatives → Research non-vendor options where gaps exist
  5. Check Product Family → Shared infrastructure, component reuse, cross-product UX
  6. Create TECH- Entries → Write entries using standard or reuse template
  7. Map to Risks → Cross-reference every TECH- entry with RISK- constraints

Decision Categories

CategoryDefinitionWhen to Choose
ReuseExisting asset covers this need as-isSibling product or prior work already solves this
ExtendExisting asset needs augmentationAsset exists but needs new capabilities for this product
NewNo existing asset, greenfield decisionNo prior work; need full evaluation
ReplaceExisting asset doesn't fit, needs new solutionCurrent tool/service is wrong for this product's requirements
BuildCreate custom solutionCore differentiator, no good alternatives, full control needed
BuyUse paid service or managed productCommodity capability, proven solutions exist, not a differentiator
IntegrateConnect to external platform or APIEcosystem play, user expects it, data lives elsewhere
ResearchNeed POC before decidingHigh 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

FactorFavors Reuse/ExtendFavors Buy (Vendor)Favors Buy (Non-Vendor)Favors Build
Existing assetAlready deployed and workingVendor has a productNon-vendor product fits betterNothing fits
DifferentiationNot relevantCommodity capabilityCommodity capabilityCore to value prop
Vendor alignmentAlready committedVendor product fitsVendor has gap or poor fitNo vendor option
ComplianceAlready compliantVendor product is compliantNon-vendor has compliance certMust control compliance
Team expertiseTeam already operates itManaged service, less expertise neededTeam knows this toolTeam has deep knowledge
CostSunk cost, incremental onlyReasonable vendor pricingBetter price/fit ratioLong-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:

  1. "Does an existing product family exist with established technology choices?"

    • If YES → Load references/brownfield.md for asset discovery workflow
    • If NO → Proceed to Step 2 with all layers marked as "New"
  2. "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
  3. "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
  4. "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 AreaExisting AssetStatus
[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:

CategoryCriteriaAction
ReuseExisting asset covers the need as-isCreate lightweight TECH- entry (use assets/tech-reuse.md)
ExtendExisting asset needs augmentationCreate TECH- entry documenting what changes are needed
NewNo existing asset, greenfield decisionProceed to Steps 3-4 for full evaluation
ReplaceExisting asset is wrong for this productProceed 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:

LayerQuestions to AnswerCommon Options
FrontendFramework? Hosting? Mobile/Web?React, Vue, Next.js, Vercel
BackendLanguage? Framework? Serverless?Node, Python, Go, AWS Lambda
DatabaseSQL/NoSQL? Managed?PostgreSQL, MongoDB, Supabase
AuthBuild or buy? SSO?Auth0, Clerk, Firebase Auth
PaymentsIf monetized, processor?Stripe, Paddle, LemonSqueezy
InfrastructureCloud? Edge? CDN?AWS, GCP, Vercel, Cloudflare
IntegrationsExternal services? APIs?Depends on product
AI/MLModels? Services?OpenAI, Anthropic, local models
AnalyticsProduct analytics? Error tracking?Mixpanel, PostHog, Sentry
DevOpsCI/CD? Monitoring?GitHub Actions, Datadog

Step 3: Evaluate Vendor Fit

For each "New" or "Replace" layer from Step 2:

  1. If your team has vendor constraints (AWS-only, Azure-first, etc.), check if the preferred vendor has a product for this capability
  2. Evaluate fit, compliance status, and cost
  3. If vendor product fits → create TECH- entry with Category: Buy
  4. If vendor product has poor fit or gaps → proceed to Step 4

Evaluation criteria for vendor products (or any Buy option):

CriterionQuestions
FitDoes the vendor product solve our specific need? Feature gaps?
ComplianceDoes it meet our regulatory requirements (from RISK- entries)?
CostWhat's the pricing at your current stage? Can you afford it until you reach product-market fit? (Cost optimization comes later, not MVP.)
MaturityProduction-ready? Documentation quality? Active development?
IntegrationHow 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:

  1. Research 2-3 non-vendor alternatives
  2. Score against the same criteria from Step 3
  3. If a clear winner exists → create TECH- entry with decision
  4. 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:

  1. For each RISK- entry, verify at least one TECH- entry addresses it
  2. For each TECH- entry, verify it doesn't introduce new unmitigated risks
  3. Document the mapping in a summary table:
RiskScoreTechnology 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

PatternSignalFix
Resume-driven development"Let's use [hot new tech]"Choose boring technology for non-differentiators
Evaluate everythingScoring auth when Keycloak already worksCategorize Reuse/Extend/New/Replace first
Greenfield assumption"Pick a frontend framework" when React existsDiscover existing assets before evaluating
Build everythingNo Buy/Integrate decisionsChallenge: is this really a differentiator?
Buy everythingNo Build decisionsSome things must be custom for your moat
Analysis paralysisResearch everythingTime-box research; decide with 70% confidence
Ignoring constraintsTech choice conflicts with RISK-Review RISK- entries before finalizing
Premature cost optimization"We must use the cheapest database" for MVPOptimize for speed-to-market and quality first. Reduce costs after product-market fit.
Cost blindnessNo cost estimates on Buy decisionsEvery 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- entryTECH-003 references no FEA- or RISK-Mandatory cross-reference in template
SoT contaminationDecision rationale essays in SoT templateMethodology 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

ConsumerWhat It UsesExample
v0.6 Architecture DesignTECH- selections define the systemTECH-001 → ARC-001 frontend architecture
v0.6 Technical SpecificationTECH- informs API designTECH-003 → API-XXX data model constraints
v0.7 Build ExecutionTECH- Research items become spikesTECH-005 (Research) → EPIC task
Hiring/ResourcingTECH- Build items define skills neededTECH-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_conformance readiness dimension. See docs/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

CategoryWhat It CoversExample Decisions
StructureComponent organization, boundariesMonolith vs microservices, module structure
IntegrationExternal service connectionsAPI gateway pattern, webhook handlers
SecurityAuth, authorization, data protectionJWT strategy, role-based access
PerformanceScaling, caching, optimizationCDN strategy, database indexing
DataStorage, flow, consistencyEvent sourcing, CQRS, replication
DevOpsDeployment, monitoring, CI/CDContainer orchestration, observability

Design Process

  1. Pull TECH- decisions — What technologies are we building with?
  2. Pull RISK- constraints — What must the architecture account for?
  3. Pull FEA- features — What must the system do?
  4. Define system boundaries — What's in/out of scope?
  5. Map component relationships — How do parts connect?
  6. Document integration patterns — How do Buy/Integrate items connect?
  7. 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

PatternWhen to UseExample
MonolithMVP, small team, unclear boundariesSingle Next.js app
Modular MonolithGrowing codebase, clear domainsModules with defined interfaces
MicroservicesClear boundaries, scaling needsSeparate auth, billing, core services

Rule for MVP: Start monolith, extract services when you have evidence of need.

For Buy/Integrate Components

PatternWhen to UseExample
Direct IntegrationSimple, trusted serviceCall Stripe API directly
Adapter LayerWant to swap providers laterAbstract over auth provider
Event BridgeAsync, decoupledWebhooks → 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:

ElementSymbolPurpose
Service/ComponentBoxInternal services, modules
External SystemCloud/cylinderThird-party services, DBs
Trust BoundaryDashed lineSecurity perimeters
Data FlowArrowHow data moves
Integration PointDiamondWhere 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:

RiskArchitecture Response
RISK-001: API dependency outageARC-010: Add retry + circuit breaker
RISK-003: Data breachARC-005: Encryption at rest + transit
RISK-007: Scaling bottleneckARC-012: Cache layer, read replicas

Anti-Patterns to Avoid

Anti-PatternSignalFix
Architecture astronautOver-engineering for 1000x scaleDesign for 10x current needs
Missing boundariesEverything can call everythingDefine clear interfaces
Ignoring RISK-Architecture doesn't address risksMap each High RISK- to ARC-
Vendor lock-inNo abstraction over critical servicesAdd adapter layer for switching
Diagram without decisionsPretty pictures, no ARC- recordsEvery box needs documented rationale
Premature microservices5 services for MVPStart 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:

ConsumerWhat It UsesExample
Technical SpecificationARC- informs API designARC-001 (monolith) → unified API surface
v0.7 Build ExecutionARC- defines EPIC scopeARC-003 (auth module) → EPIC-02
Development Graph (v0.7)ARC- conformance rules become code checksARC-004 (no UI import in engine/) → architecture_conformance verdict
Infrastructure SetupARC- drives deploymentARC-010 (edge caching) → CDN config
Security ReviewSecurity ARC- entriesARC-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

TypeWhat It DefinesWhen Required
ENV-001Development environment (local setup)Always
ENV-002CI/CD pipeline configurationWhen using automated testing/deployment
ENV-003Production infrastructureWhen 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.

FactorCLIMCP
Works in CI/CDYesNo
Works locallyYesYes (limited contexts)
Structured outputJSON, exit codesVaries
DebuggingStandard toolsHarder

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

  1. Pull TECH- decisions — What technologies are we using?
  2. Pull ARC- decisions — What architecture patterns apply?
  3. Inventory tooling needs — What do developers need installed?
  4. Categorize by scope — Global vs per-project
  5. Define configuration files — What configs are needed?
  6. Create verification steps — How to confirm setup works?
  7. 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-PatternSignalFix
Global package pollutionnpm install -g for project packagesUse devDependencies
Missing verificationNo way to confirm setupAdd verification commands
Prose instead of structureLong paragraphs describing setupUse tables and code blocks
MCP over CLIUsing MCP when CLI existsPrefer CLI for portability
Undocumented configConfig files without explanationDocument purpose of each file
Implicit dependenciesSetup fails without warningList 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:

ConsumerWhat It UsesExample
v0.7 Build ExecutionENV-001 defines dev setupDeveloper follows ENV-001 to set up
OnboardingENV-001 as setup guideNew dev uses ENV-001 for first day
CI/CDENV-002 defines pipelineGitHub Actions mirrors ENV-002
DeploymentENV-003 defines infrastructureDEP- 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

TypeWhat It DefinesExample
API-Endpoint contractsPOST /users, GET /reports/:id
DBT-Data model/schemaUsers table, Reports table

Rule: Every API- should know which DBT- it reads/writes. Every DBT- should know which API- accesses it.

Specification Process

  1. Pull ARC- decisions — System structure and boundaries

  2. Pull TECH- Build items — What we're implementing

  3. Pull UJ- journeys — User flows the API must support

  4. Pull SCR- screens — UI data requirements

  5. Define API contracts for each endpoint:

    • What's the request/response shape?
    • What auth is required?
    • What errors can occur?
  6. Define data models for each entity:

    • What fields exist?
    • What relationships?
    • What constraints?
  7. 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

PrincipleGuidanceExample
Resource-orientedURLs are nouns, not verbs/reports not /createReport
Consistent namingPlural nouns, kebab-case/data-sources not /dataSource
StatelessNo server-side sessionsAuth via token, not cookie session
VersionedPrefix for breaking changes/v1/reports
Documented errorsClear codes and messages{ error: { code: "LIMIT_EXCEEDED", message: "..." } }

Data Model Principles

PrincipleGuidanceExample
NormalizedAvoid redundancy (unless denormalized for performance)User name in users table, not duplicated
Audit trailcreated_at, updated_at on all tablesTrack when records change
Soft deletedeleted_at instead of hard delete (when needed)Recover deleted data
Foreign keysEnforce referential integrityuser_id → users.id
Index strategyIndex fields in WHERE and JOINFilter 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-PatternSignalFix
API/UI mismatchScreen needs data not in any APIAdd API- or modify existing
Schema sprawl50+ tables for MVPConsolidate; YAGNI applies
Missing constraintsNo validation, anything acceptedAdd BR- enforcement
N+1 queries baked inAPI design requires multiple calls for one viewAdd compound endpoints
No error handlingOnly happy path documentedDefine all error responses
Vague typesdata: anySpecify 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:

ConsumerWhat It UsesExample
v0.7 Epic ScopingAPI- and DBT- define EPIC scopeEPIC-01 implements API-001–005
v0.7 Test PlanningAPI- defines test contractsTEST-001 validates API-001
v0.7 Implementation LoopAPI-/DBT- are implementation tasksCode implements API-001
API DocumentationAPI- becomes OpenAPI specSwagger 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

SizeCharacteristicsAction
Right-sized3-5 API endpoints, 2-4 DBT tables, 1-2 UJ flowsGood fit ✓
Too big>10 APIs, >5 tables, multiple unrelated featuresSplit by domain
Too smallSingle endpoint, no meaningful deliverableMerge 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.

DimensionTargetRationale
Pre-load context<100k tokensSoT files + EPIC + code references
Working room>100k tokensSpace for tool outputs, debugging, iteration
Session goal1 checkpointClear "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-endpoints
  • epic/EPIC-02-user-dashboard
  • epic/EPIC-03-payment-integration

Workflow:

  1. EPIC created → git checkout -b epic/EPIC-{NUMBER}-{slug}
  2. Work happens → Commits reference IDs in messages
  3. Checkpoints → Commit with state saved in EPIC Section 1
  4. EPIC complete → PR opened
  5. PR merged → Branch deleted, EPIC marked Complete

Scoping Process

  1. Inventory implementation items from API-, DBT-, FEA-, ARC-

    • What must be built?
  2. 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.
  3. Size each potential EPIC against context window capacity

    • Can an agent hold all relevant IDs in one session?
  4. Sequence EPICs by dependencies

    • What must be built first?
    • What enables other EPICs?
  5. Create EPIC- entries with full ID references

  6. Validate: Can an agent complete this EPIC without needing more context than fits in a session?

Sequencing Framework

OrderPriorityRationaleExamples
1Infrastructure EPICsEverything depends on theseAuth, DB setup, project scaffold
2Core data model EPICsFoundation for featuresUser, Workspace, base entities
3Critical path EPICsJourneys that drive KPIsUJ- that affects KPI-001
4Supporting feature EPICsSecondary featuresSettings, 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:

PhasePurposeActivities
A: PlanLoad contextRead EPIC, load referenced IDs, verify Session State
B: DesignUpdate SoTDraft/refine ID entries in SoT/ before coding
C: BuildImplementWork through Context Windows, test-first
D: ValidateVerifyRun tests, manual checks, traceability audit
E: FinishClean upUpdate SoT, archive temp/, mark complete

Anti-Patterns to Avoid

Anti-PatternSignalFix
Epic explosion20+ EPICs for MVPConsolidate; most MVPs need 3-7
One mega-EPICEverything in one EPICSplit by architectural boundary
No ID referencesEPIC without BR-, API-, DBT- linksEvery EPIC must reference SoT/
Circular dependenciesEPIC-01 needs EPIC-02 needs EPIC-01Identify shared foundation, extract to EPIC-00
Context overloadAgent can't hold full EPIC contextSplit into smaller Context Windows
Missing sequencingNo build order definedEstablish explicit dependency chain
Vague objectives"Build the backend"Specific, measurable: "Implement API-001–005"
Silent scope assumptionsEPIC assigns items without explaining boundary rationaleEvery 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:

ConsumerWhat It UsesExample
Test PlanningEPIC scope defines test boundariesTEST- entries for EPIC-01 scope
Implementation LoopEPIC is execution unitWork happens inside EPIC context
Session ManagementSession State section tracks progressResume from where we left off
Progress TrackingEPIC state shows overall progress3/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/@verifies tags 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 ElementTag PatternExample
API handler@implements API-XXXAPI endpoint function
Business logic@implements BR-XXXValidation, rules
Database model@implements DBT-XXXSchema definition
UI component@implements SCR-XXXScreen component
Test file@tests TEST-XXXTest 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:

SituationAction
Spec matches implementationNo update needed
Implementation reveals new constraintAdd BR- entry to specs/
API shape changed during buildUpdate API- entry
New field needed in schemaUpdate DBT- entry
Spec was wrong/incompleteFix spec AND code
Discovered edge caseAdd 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
  • @implements tags 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)

SignalAction
Can't write testRequirement unclear → revisit spec
Test keeps failingImplementation wrong OR spec wrong → investigate
Need code outside EPIC scopeWrong EPIC boundaries → re-scope
Lost context mid-sessionLoad Session State, verify EPIC context
Spec and code divergingStop, update spec to match reality
Test is testing implementationRewrite to test behavior
Writing code not required by any TEST-Speculative — remove it, or write the TEST- first
Editing files outside current Context WindowScope creep — note in Assumptions & Ambiguities table, defer

Anti-Patterns to Avoid

Anti-PatternSignalFix
Test-afterCode written, then "add tests"Write TEST- implementation first
Spec driftCode diverges from specs/Update SoT during implementation
Missing traceabilityCode has no @implements tagsAdd tags as you write
Session amnesiaNo Session State updateALWAYS update before stopping
Context switchingJumping between EPICsFinish one EPIC before starting another
One-shot buildingNo iteration, just code dumpFollow the loop: test → code → tag
Orphaned codeCode not linked to any IDEvery function serves an ID
Speculative error handlingtry/catch for scenarios no TEST- coversRemove 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 IDsAlways 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.json rebuilt; implementation_coverage ≥ threshold (no scoped spec unbuilt, no unbuilt_specs cap) and no architecture_conformance violations

Downstream Connections

Implementation Loop outputs feed into:

ConsumerWhat It UsesExample
v0.8 ReleaseCompleted EPICs ready for deploymentAll TEST- pass, SoT current
Code Review@implements tags for contextReviewer knows which BR- to check
Readiness (v0.7)Development Graph build-vs-blueprintimplementation_coverage + architecture_conformance from status/devgraph.json
HeartBeatThe Development Graph as a live pulseRenders built / unbuilt / drifted across the codebase
Future SessionsSession State for continuityResume exactly where left off
MaintenanceTraceability 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

TypeWhat It TestsWhen to UseScope
UnitSingle function/methodBusiness logic, calculationsSmallest unit
IntegrationComponent boundariesAPI ↔ DatabaseModule level
E2EFull user flowCritical journeysSystem level
ContractAPI shape/typesExternal integrationsInterface level
PerformanceSpeed/loadCritical pathsBenchmark

Coverage Requirements

ID TypeMinimum CoverageRationale
API-1 happy path + 1 error case per endpointEndpoints are integration points
BR-1 test per rule, including boundary casesRules are product logic
UJ-1 E2E test per core journeyJourneys are user value
DBT-Constraint tests for critical fieldsData integrity is foundational

Test Planning Process

  1. Pull EPIC- scope

    • Which APIs, DBTs, BRs are included?
  2. 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.
  3. For each BR-: Define rule validation tests

    • Positive: Rule allows expected behavior
    • Negative: Rule blocks invalid behavior
    • Boundary: Edge cases at limits
  4. For each UJ-: Define end-to-end flow tests

    • Complete journey from trigger to value moment
  5. For each DBT-: Define data integrity tests

    • Constraints enforced (unique, not null)
    • Relationships maintained (FK integrity)
  6. Create TEST- entries linked to implementation IDs

  7. 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

PriorityCriteriaExample
CriticalBreaks core value, data loss possibleAuth, payments, data creation
HighBlocks key journey, user-facing errorOnboarding, main features
MediumDegrades experience, workaround existsSettings, secondary features
LowEdge case, admin-only, cosmeticRare 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-PatternSignalFix
Tests after code"We'll add tests later"Define TEST- before writing code
Only happy pathNo error case testsEvery API needs at least 1 error test
Orphaned testsTEST- not linked to API-/BR-/UJ-Every test must trace to a spec ID
Test explosion200+ tests for MVPFocus on critical paths; 30-50 typical
Vague assertions"System works correctly"Specific, measurable outcomes
No automation pathManual-only critical testsCritical tests must be automatable
Testing implementationTest verifies internal detailsTest behavior, not implementation
Tests from assumptionsTEST- contains details not in any specEvery 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:

ConsumerWhat It UsesExample
Implementation LoopTEST- defines acceptance criteriaEPIC done when TEST-001–010 pass
EPIC Validation (Phase D)TEST- list for validation checklistRun all TEST- for EPIC
CI/CDTEST- becomes automated suiteTEST- entries → test files
Code ReviewTEST- 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.

ModeWhat this skill produces
quickOne release format (markdown for site); one channel mapping; minimum-viable changelog page
standardRelease categorization + 2–3 channel mappings; per-channel format templates; publish cadence; attribution plan
deepFull 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

  1. 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.
  2. 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)
  3. 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
  4. 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
  5. 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.
  6. Plan attribution — Every channel-published release gets a UTM. Track changelog → signup conversion to identify which categories convert.

Example

A developer-tools product ships:

ItemCategoryChannels
New /api/v2/webhooks endpointNew featureBlog (full), email, Twitter, LinkedIn, RSS
/api/v1/webhooks deprecation (sunset in 6mo)DeprecationEmail (high-priority), blog, RSS
30% faster response time on heavy queriesImprovementTwitter, weekly digest
Fixed: webhook signing edge caseFixChangelog page only
Internal: refactored auth middlewareInternal(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

TriggerMode
First release post-launch (no changelog system yet)quick
Standard launch cadence stabilizingstandard
Pre-investor / pre-Series A — changelog as proof of velocitydeep
API or developer-tool productdeep (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 dedicated SoT/SoT.CHANGELOG.md if 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

PatternSignalFix
Dumping internal commitsChangelog reads like git logCategorize; publish only what users care about
Same content everywhereSame blog post copy-pasted to Twitter and LinkedInEach 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 voiceCustomer changelog uses internal jargonTone-shift per audience; engineer changelog ≠ end-user changelog
No attributionChangelog publishes but no idea what convertsUTM every link; track per-channel conversion
Sporadic cadencePublish heavily for 2 months, then quiet for 6Pick per-release or digest cadence; commit to it
Breaking change buriedHidden in a sea of small itemsBreaking 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

ConsumerWhat it usesExample
Launch Channels (ORB)Changelog is an Owned channel; rolls into mix matrixBlog-changelog = Owned-content
Launch MetricsPer-channel changelog conversion targetsKPI-changelog-blog-signups
Feedback Loop SetupChangelog reader comments become CFD-Blog comment threads → CFD- pattern
AEO AuditHigh-traffic changelog posts become AI citation sourcesChangelog entries cited by AI search
v1.0 Case Study BuilderShipped 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-updates skill (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.

ModeWhat this skill produces
quickOne metric / config / dataset baselined; weekly compare schedule; simple threshold alert
standard3–5 things monitored; baseline + tiered thresholds (warn / critical); compare cadence; history retention
deepFull 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

  1. 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)
  2. Capture the baseline — Take a snapshot. Date it. Store in version control or a known location (status/baselines/, monitoring/snapshots/, etc.).
  3. 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)
  4. 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
  5. 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
  6. 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>.sh or equivalent) when automatable

When to Use It

TriggerMode
Post-launch — need ongoing watch on KPIsstandard
AEO Audit results to maintainstandard
Competitor feature parity trackingstandard
Vendor / third-party pricing watchquick
Performance regression huntingdeep
Infrastructure cost trendquick

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

PatternSignalFix
Stale baselineComparing 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 noiseCritical alert fires every week for 2% movementThreshold is too tight; widen warn, tighten critical
No history logSnapshot, compare, alert, forgetAppend-only history is the whole point; without it, you can't see trends
Monitoring everything50 MON-DRIFT-* entries, nobody reads anyPick the 3–5 things that matter; archive the rest
No causal interpretation"Drift detected" with no investigation pathEach drift signal should map to candidate causes (recent release, competitor move, AI surface change)
Drift instead of alertingUsing drift for things that need absolute thresholdsDrift = 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

ConsumerWhat it usesExample
Runbook Creation (RUN-)Drift criticals trigger investigation runbooksMON-DRIFT-AEO critical → RUN-investigate-aeo-loss
Launch MetricsDrift on launch KPIs informs go/no-go decisionsKPI-activation drift ≥10% → re-look at GTM
Feedback Loop SetupDrift in customer-facing metrics drives CFD- investigationActivation drift down → CFD- interview cohort
v0.9 AEO Audit (re-run)Drift in AI search positions triggers re-auditAEO drift → re-run aeo-audit
v1.0 Continuous DiscoveryDrift patterns inform discovery questions"Why is X drifting?" → Teresa Torres discovery

Detailed References

  • AgriciDaniel's seo-drift skill — 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.

ModeWhat this skill produces
quick3-stage lifecycle (Anonymous → Lead → Customer); single handoff rule; SLA per stage
standardFull 5-stage lifecycle (Anonymous → MQL → SQL → Opportunity → Customer); entry/exit criteria; handoff payload spec; SLAs
deepFull 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

  1. 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
  2. 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
  3. 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.
  4. Map ownership — Who owns the lead at each stage:
    • Anonymous: marketing automation
    • MQL: BDR/SDR
    • SQL: AE / founder
    • Opportunity: AE / founder
    • Customer: CS / founder
  5. 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)
  6. 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.
  7. 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.

StageEntry criteriaExit criteriaOwnerSLA
AnonymousAny first touchFilled form OR signed upMarketingn/a
MQLFilled high-intent form (demo request, pricing page)BDR qualifies in OR disqualifiesBDR1 business hour
SQLBDR confirms fit + intentAE accepts OR rejectsBDR → AE30 min
OpportunityAE held discovery, budget + authority confirmedClosed-won OR closed-lostAE24 hr per touch
CustomerClosed-won contract signedChurn OR expandCSOnboarding 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

TriggerMode
B2B / sales-assisted product, pre-launchstandard
Hybrid PLG + Sales motiondeep
Pure self-serve consumer productskip — overkill
Adding human sales to existing self-servestandard
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

PatternSignalFix
MQL = "anyone who filled a form"High-volume MQLs with 1% SQL conversionTighten MQL entry criteria; add fit-signal scoring
No rejection routingLeads die when SQL → AE rejectsDefine where rejected leads go (nurture, disqualified, requeue)
SLA without escalation"Respond in 1 hour" with no consequence if missedSLA must have an escalation path
Handoff without payloadNew 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/OPPUse Signup → Activated → Paid; no human handoff
No SLA monitoringSLAs exist on paper, missed in practiceDrift-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

ConsumerWhat it usesExample
Launch Channels (ORB)Each channel's leads enter the lifecycle at AnonymousGTM-002 (Product Hunt) → Anonymous → MQL routing
Cold Outreach (Tiered)Tier 1/2/3 sequences map to lifecycle stagesTier 1 = SQL-tier ABM; Tier 3 = MQL nurture
Launch MetricsStage conversion rates become KPI- entriesKPI-MQL-to-SQL-conversion
Feedback Loop SetupRejected leads' "why we passed" reasons feed CFD-Pattern: "too small" rejections → CFD- pricing signal
Drift MonitoringSLA drift catches process decayMON-DRIFT-MQL-response-SLA

Detailed References

  • alirezarezvani's marketing-ops and revenue-operations skills (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.

ModeWhat this skill produces
quickRED metrics on critical path only; 3–5 alerts linked to RUN-; single overview dashboard
standardRED + USE coverage; SLOs for tier-1 services; full alert routing to RUN-; dashboards by audience
deepLayered 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

LayerWhat to MeasureWhy It Matters
InfrastructureCPU, memory, disk, networkSystem health foundation
ApplicationLatency, errors, throughputUser-facing performance
BusinessSignups, conversions, revenueProduct health
User ExperiencePage load, interaction timeReal user impact

Execution

  1. Define SLOs (Service Level Objectives)

    • What uptime do we promise?
    • What latency is acceptable?
    • What error rate is tolerable?
  2. 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
  3. Set alert thresholds

    • Warning: Investigate soon
    • Critical: Act immediately
    • Base on SLOs and historical data
  4. Map alerts to runbooks

    • Every critical alert → RUN- procedure
    • No alert without action path
  5. Design dashboards

    • Overview: System health at a glance
    • Deep-dive: Per-service details
    • Business: KPI tracking
  6. 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:

MetricWhat It MeasuresAlert Threshold
RateRequests per secondAnomaly detection
ErrorsFailed requests / total>1% warning, >5% critical
DurationRequest latency (p95, p99)>500ms warning, >2s critical

The USE Method (Infrastructure Monitoring)

For each resource (CPU, memory, disk, network):

MetricWhat It MeasuresAlert Threshold
Utilization% of capacity used>80% warning, >95% critical
SaturationQueue depth, waiting>0 for critical resources
ErrorsError count/rateAny errors = investigate

SLO Framework

TierAvailabilityLatency (p95)Use For
Tier 199.99% (52 min/yr)<100msPayment, auth
Tier 299.9% (8.7 hr/yr)<500msCore features
Tier 399% (3.6 days/yr)<2sBackground jobs

Alert Severity Matrix

SeverityUser ImpactResponse TimeNotification
CriticalService unusable<5 minPagerDuty (wake up)
WarningDegraded experience<30 minSlack (business hours)
InfoNo immediate impactNext dayDashboard/log

Dashboard Design Principles

PrincipleImplementation
Answer questionsEach panel answers "Is X working?"
HierarchyOverview → Service → Component
ContextShow thresholds, comparisons
ActionableLink to runbooks from alerts
FastQuick load, auto-refresh

Anti-Patterns

PatternSignalFix
Alert fatigueToo many alerts, team ignoresTune thresholds, remove noise
No runbook linkAlert fires, no one knows what to doEvery alert → RUN-
Vanity metrics"1 million requests!" without contextFocus on user-impacting metrics
Missing baselinesNo historical comparisonEstablish baselines before launch
Over-monitoring500 metrics, can't find signalFocus 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

ConsumerWhat It UsesExample
On-Call TeamMON- alerts trigger responseMON-003 → page engineer
v0.9 Launch MetricsMON- provides baseline dataMON-001 baseline → KPI-010 target
Post-MortemsMON- data for incident analysis"MON-005 showed spike at 14:32"
Capacity PlanningMON- trends inform scalingUSE metrics → infrastructure planning
DEP- RollbackMON- thresholds trigger rollbackMON-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.

ModeWhat this skill produces
quickStaging→prod only; 3–5 release criteria; one rollback trigger
standardDev/staging/preview/prod environments; full criteria checklist; multiple rollback triggers; post-deploy validation
deepFull 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

ComponentPurposeOutput
Deployment EnvironmentWhere code runsDEP- (environment config)
Release CriteriaWhat must be true to deployDEP- (checklist)
Rollback TriggersWhen to revertDEP- (conditions)
Validation StepsHow to verify successDEP- (post-deploy checks)

Execution

  1. Inventory completed EPICs

    • Which EPIC- entries are "Complete"?
    • What API-, DBT-, FEA- are included in this release?
  2. Define deployment environments

    • Staging, Production, Preview
    • Environment-specific configurations
    • Secrets management approach
  3. Establish release criteria

    • All TEST- pass in staging
    • Performance baselines met (from MON-)
    • No critical RISK- blockers
    • Security review complete
  4. Define rollback triggers

    • Error rate thresholds
    • Latency thresholds
    • User-reported critical issues
    • Data integrity concerns
  5. Document validation steps

    • Post-deployment smoke tests
    • Key journey verification (UJ-)
    • Metric baseline confirmation
  6. 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

StageEnvironmentPurposeGate
1DevelopmentEngineer testingTests pass locally
2StagingIntegration testingAll TEST- pass
3PreviewStakeholder reviewSign-off from PM
4ProductionLive usersAll DEP- criteria met

Release Criteria Categories

CategoryExamplesPriority
FunctionalTests pass, features workMust-have
PerformanceLatency <200ms, throughput >100rpsMust-have
SecurityNo critical vulns, secrets rotatedMust-have
OperationalRunbooks ready, monitoring activeShould-have
DocumentationRelease notes, API docs updatedShould-have

Rollback Strategy Patterns

PatternWhen to UseComplexity
Blue-GreenNeed instant rollback, can afford 2x infraMedium
CanaryGradual rollout, catch issues earlyHigh
RollingZero-downtime, standard approachLow
Feature FlagsDecouple deploy from releaseMedium

Anti-Patterns

PatternSignalFix
Deploy and prayNo validation steps definedAdd DEP- validation entries
Manual everythingNo automation, error-proneAutomate repeatable steps
No rollback plan"We'll figure it out"Define triggers and procedures upfront
Environment driftStaging doesn't match productionInfrastructure as code, sync configs
Missing criteria"It works on my machine"Formal DEP- criteria checklist
Unclear ownershipNo one knows who approvesAssign 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

ConsumerWhat It UsesExample
Runbook CreationDEP- rollback procedures become runbook inputsDEP-003 → RUN-005
Monitoring SetupDEP- thresholds inform alertingDEP-003 (2% error) → MON-001
v0.9 GTM StrategyRelease readiness gates launchAll DEP- met → GTM-001
EPIC- Future ReleasesDEP- becomes template for next releaseDEP-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.

ModeWhat this skill produces
quick2–3 runbooks covering the top RISK-/MON- pairs
standardIncident + deployment + maintenance runbooks linked to MON- and DEP-, with escalation paths
deepFull 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

CategoryPurposeTrigger
Incident ResponseHandle production issuesAlert fires, user reports
DeploymentExecute release proceduresScheduled release
MaintenanceRegular operational tasksScheduled windows
RecoveryRestore from failuresDisaster scenario
EscalationRoute to right peopleIssue beyond capability

Execution

  1. Identify critical scenarios

    • What alerts from MON- require action?
    • What deployment steps from DEP- need procedures?
    • What RISK- entries need response plans?
  2. Map each scenario to a runbook

    • One runbook per distinct scenario
    • Clear scope—what it covers and doesn't
  3. Document step-by-step procedures

    • Numbered steps, no ambiguity
    • Include commands, links, contact info
    • Assume operator has minimal context
  4. Define escalation paths

    • When to escalate
    • Who to contact
    • What information to provide
  5. Add verification steps

    • How to confirm the issue is resolved
    • What metrics should normalize
  6. 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.

ModeWhat this skill produces
quick5 target queries × 2 AI surfaces (ChatGPT + Perplexity); top 3 gaps with fixes
standard10–15 queries × 3–4 AI surfaces; full Coverage Matrix; ranked fix backlog
deep20–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

  1. 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").
  2. 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.
  3. 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)
  4. 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
  5. 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:

SurfaceMentioned?PositionAccuracyCitations
ChatGPTNon/an/a5 sources, none ours
PerplexityYes4th of 5"an analytics tool" (wrong category)Sources include our pricing page only
AI OverviewsNon/an/aG2, 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:

  1. Publish CRO-anchored guide (prd-v09-alternatives-pages handles competitor variants)
  2. Rewrite product schema (JSON-LD) with the Dunford category claim
  3. 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

TriggerMode
Pre-launch sanity check (before paid channels activate)quick
Standard launch wave auditstandard
Quarterly retention/competitive intelligence reviewdeep
After major positioning change (re-test)standard
When organic signups stall and paid CAC risesdeep

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

PatternSignalFix
Vanity queriesAuditing "best [exact product name]" — you'll always win that oneUse buyer-intent queries the buyer would actually type
No timestamp / no re-testResults saved but never re-testedAI surfaces change; re-test every fix within 2 weeks
Surface monocultureOnly testing ChatGPTEach surface has different model/data; minimum 3 surfaces
Fix all gaps equally20 gaps, parallel work, no rankingRank 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 analysisKnowing you're absent but not whyCitation 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

ConsumerWhat it usesExample
Alternatives PagesComparison-gap fixes become alternatives-page targets"X vs us" comparison gap → SCR-ALT- page
Positioning (re-run)Category-coding gaps signal positioning weaknessRecurring miscategorization → re-run prd-v09-positioning-dunford
Launch MetricsCoverage Matrix becomes a KPI baselineKPI-AEO-coverage%
v1.0 Continuous DiscoveryRecurring gap patterns inform discovery questions"Users keep finding competitor X — why?"

Detailed References

  • Sanity team's seo-aeo-best-practices skill (VoltAgent index)
  • Princeton AI Search benchmark studies
  • (No bundled references/ — AI surfaces change too quickly to canonize)
prd-v09-alternatives-pagesprd-v09-cold-outreach-tieredprd-v09-feedback-loop-setupprd-v09-gtm-strategyprd-v09-hn-reddit-launchprd-v09-launch-channels-orbprd-v09-launch-metricsprd-v09-offer-construction-hormoziprd-v09-positioning-dunfordprd-v10-case-study-builderprd-v10-chasm-adoption-mooreprd-v10-continuous-discovery-torresprd-v10-mom-test-interviewprd-v10-testimonial-collector

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

OutputFormatDestination
ArchitectureARC-XXX entriesSoT/SoT.TECHNICAL_DECISIONS.md
Tech decisionsTECH-XXX entriesSoT/SoT.TECHNICAL_DECISIONS.md
API contractsAPI-XXX entriesSoT/SoT.API_CONTRACTS.md
Schema definitionsDBT-XXX entriesSoT/SoT.DATA_MODEL.md
Test specificationsTEST-XXX entriesSoT/SoT.TESTING.md
Deployment configDEP-XXX entriesSoT/SoT.DEPLOYMENT.md
RunbooksRUN-XXX entriesSoT/SoT.DEPLOYMENT.md
Implementation workEPIC filesepics/

Skills I Invoke

StageSkillPurpose
v0.5prd-v05-technical-stack-selectionEvaluate and select technologies
v0.6prd-v06-architecture-designDefine system architecture
v0.6prd-v06-technical-specificationCreate API and data model specs
v0.6prd-v06-environment-setupDocument dev environment requirements
v0.7prd-v07-epic-scopingBreak work into context windows
v0.7prd-v07-test-planningDefine test coverage
v0.7prd-v07-implementation-loopExecute build with traceability
v0.8prd-v08-release-planningDefine deployment criteria
v0.8prd-v08-runbook-creationCreate operational playbooks
v0.8prd-v08-monitoring-setupEstablish 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

OutputFormatDestination
PRD section updatesMarkdown with lifecycle labelsPRD.md
Research insightsCFD-XXX entriesSoT/SoT.customer_feedback.md
Business constraintsBR-XXX entriesSoT/SoT.BUSINESS_RULES.md
User journeysUJ-XXX entriesSoT/SoT.USER_JOURNEYS.md
Risk registerRISK-XXX entriesPRD.md v0.5 section

Skills I Invoke

StageSkillPurpose
v0.1prd-v01-problem-framingStructure pain points into problem statements
v0.1prd-v01-user-value-articulationTransform pains into value propositions
v0.2prd-v02-competitive-landscape-mappingMap competitor positioning
v0.2prd-v02-product-type-classificationDetermine product strategy type
v0.3prd-v03-outcome-definitionDefine measurable KPIs
v0.3prd-v03-pricing-modelStructure pricing approach
v0.3prd-v03-moat-definitionDefine defensibility strategy
v0.3prd-v03-features-value-planningPrioritize features by value
v0.4prd-v04-persona-definitionSynthesize behavioral personas
v0.4prd-v04-user-journey-mappingMap trigger-to-value flows
v0.5prd-v05-risk-discovery-interviewSurface 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

OutputFormatDestination
Launch planGTM-XXX entriesPRD.md v0.9 section
Success metricsKPI-XXX entriesREADME.md metrics section
Post-launch feedbackCFD-XXX entriesSoT/SoT.customer_feedback.md
Iteration insightsCFD-XXX entries→ HORIZON for next cycle

Skills I Invoke

StageSkillPurpose
v0.9prd-v09-gtm-strategyDefine go-to-market approach
v0.9prd-v09-launch-metricsEstablish success measurement
v0.9prd-v09-feedback-loop-setupCreate 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

OutputFormatDestination
Screen definitionsSCR-XXX entriesSoT/SoT.USER_JOURNEYS.md
Design componentsDES-XXX entriesSoT/SoT.DESIGN_COMPONENTS.md
Wireframes/prototypesLinks in DES-XXXExternal tool + reference
Design tokensSystem specSoT/SoT.DESIGN_COMPONENTS.md
Research insightsCFD-XXX entriesSoT/SoT.customer_feedback.md

Skills I Invoke

StageSkillPurpose
v0.4prd-v04-persona-definitionValidate persona assumptions through design
v0.4prd-v04-user-journey-mappingCo-design journey flows with HORIZON
v0.4prd-v04-screen-flow-definitionDefine screens and navigation
v0.4prd-v04-visual-prototype-gateGenerate 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