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.