PRDs & Project Context

Create product requirements and project context that humans and coding assistants can execute effectively.

Two capabilities:

PRDs & Specs - Requirements, specs, stories, acceptance criteria
Project Context - Architecture, conventions, tribal knowledge (CLAUDE.md)

Modern Best Practices (Jan 2026): Context engineering (right info, right format, right time), decision-first docs, testable requirements with acceptance criteria, metrics with formula + timeframe + data source, cross-tool portability.

Workflow (Use This Order)

Pick the deliverable (PRD, AI PRD, tech spec, story map, CLAUDE.md).
Gather inputs (problem evidence, users, constraints, dependencies, risks).
Fill the template (write decisions first; keep requirements testable).
Validate with checklists (requirements, edge cases, security/compliance as needed).
Hand off with next actions (implementation plan, owners, open questions).

Docs Folder + LLM Iteration Option (Any Repo)

Use this when a repository has a docs/ folder with:

research docs prepared for LLM consumption
feature docs/specs generated by LLMs during implementation

Run this flow before finalizing PRDs/specs:

Classify each file by purpose (Tutorial, How-to, Reference, Explanation) to prevent mixed doc types.
Tag each non-canonical file with lifecycle metadata (status, owner, last_verified, integrates_into, delete_by).
Pick one canonical doc per feature/decision; merge duplicate drafts into it.
Convert long research notes into short evidence-backed claims in canonical docs; keep links/dates for external facts.
Maintain a compact canonical library for LLMs with root anchors: AGENTS.md (agent instructions) and README.md (human + AI entrypoint), then link deeper specs from docs/.
Delete integrated drafts by delete_by date; do not keep .archive/ mirrors in docs/ unless compliance explicitly requires retention.

Quick Reference

PRDs & Specs

Task	Template
PRD creation	assets/prd/prd-template.md
Tech spec	assets/spec/tech-spec-template.md
Planning checklist	assets/planning/planning-checklist.md
Story mapping	assets/stories/story-mapping-template.md
Gherkin/BDD	assets/stories/gherkin-example-template.md
AI PRD	assets/prd/ai-prd-template.md

Project Context (CLAUDE.md)

Context Type	Template	Priority
Architecture	assets/architecture-context.md	Critical
Conventions	assets/conventions-context.md	High
Key Files	assets/key-files-context.md	Critical
Minimal Start	assets/minimal-claudemd.md	5-min
Cross-Tool	assets/cross-tool-context.md	Multi-tool

Decision Tree

User needs:
    ├─► AI-Assisted Coding?
    │   ├─ Non-trivial (>3 files)? → Planning checklist + agentic session
    │   └─ Simple (<3 files)? → Direct implementation
    │
    ├─► Repo has a docs folder with LLM-generated research/feature docs?
    │   └─ Use Docs Folder + LLM Iteration Option, then validate with qa-docs-coverage
    │
    ├─► Project Onboarding?
    │   ├─ New to codebase? → Generate CLAUDE.md
    │   └─ Quick context? → Minimal CLAUDE.md
    │
    └─► Traditional PRD?
        ├─ Product requirements? → PRD template
        ├─ AI feature? → AI PRD template
        └─ Acceptance criteria? → Gherkin/BDD

Cross-Tool Context Files

Tool	Location	Notes
Claude Code	`CLAUDE.md`, `.claude/`	Auto-loaded
Cursor	`.cursor/rules/`	Project rules
Copilot	`.github/copilot-instructions.md`	Workspace context
Generic	`AGENTS.md`	Tool-agnostic

CLAUDE.md / AGENTS.md Guidance

Start minimal: assets/minimal-claudemd.md
Add only what’s needed: assets/architecture-context.md, assets/conventions-context.md, assets/key-files-context.md, assets/dependencies-context.md, assets/tribal-knowledge-context.md
Keep it executable: commands must run; include no secrets; prefer file paths over pasted code

Do / Avoid

Do

Start with executive summary (decision, users, scope, success)
Define acceptance criteria in testable language
Keep requirements unambiguous (must/should/may)
Link to supporting docs instead of pasting

Avoid

Vague requirements ("fast", "easy") without definitions
Mixing draft notes and final requirements
Metrics without measurement plan
Docs with no owner or review cadence
Dual-state wording that mixes live behavior, target behavior, and migration behavior in one statement

LLM Ambiguity Gate (Required for planning docs)

Label every behavior as exactly one of: Live now, Target, or Transition (with owner + end condition).
Label every metric as either Reference signal or Release blocker.
Define one canonical feature-gating contract per feature; all other docs must link to it instead of restating variants.
Keep assumptions/open questions separate from final decisions.
If conflicts exist across docs, mark one canonical source and add follow-up tasks to resolve mirrors.

Context Extraction

Use:

references/architecture-extraction.md for components/data flows
references/convention-mining.md for naming/patterns
references/tribal-knowledge-recovery.md for git-history “why”
references/docs-audit-commands.md for audit commands and tool fallbacks

Quality Checklist

PRD Quality

Clear problem statement
Measurable success criteria
Unambiguous acceptance criteria
Edge cases documented
AI can execute without clarification
Every behavior is labeled Live now, Target, or Transition
Metrics are labeled Reference signal or Release blocker
Each feature-gating rule has one canonical source (no conflicting duplicates)

CLAUDE.md Quality

Architecture reflects actual structure
Key files exist at listed locations
Conventions match actual patterns
Commands actually work
No sensitive information

Resources

Resource	Purpose
references/agentic-coding-best-practices.md	AI coding patterns
references/requirements-checklists.md	PRD validation
references/traditional-prd-writing.md	Classic PRD format
references/architecture-extraction.md	Mining architecture
references/convention-mining.md	Extracting conventions
references/tribal-knowledge-recovery.md	Git history analysis
references/docs-audit-commands.md	Audit shell commands
references/stakeholder-alignment.md	Stakeholder buy-in, RACI, conflict resolution
references/acceptance-criteria-patterns.md	Testable ACs, BDD, edge case coverage
references/prd-review-facilitation.md	Running PRD reviews, feedback categorization
data/sources.json	Curated external sources

Templates

Category	Templates
PRDs	prd-template, ai-prd-template, tech-spec-template
Planning	planning-checklist, agentic-session-template
Stories	story-mapping-template, gherkin-example-template
Context	architecture, conventions, key-files, minimal-claudemd
Stack-specific	nodejs-context, python-context, react-context, go-context

Related Skills

Skill	Purpose
docs-codebase	README, API docs, ADRs
qa-docs-coverage	Documentation gaps
product-management	Product strategy
software-architecture-design	System design

Fact-Checking

Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
Prefer primary sources; report source links and dates for volatile information.
If web access is unavailable, state the limitation and mark guidance as unverified.

docs-ai-prd