Prompt History Records - Automatic Knowledge Capture

Built into Spec Kit: Every AI exchange is automatically captured as a structured artifact—no extra commands needed.

The Problem: Lost Knowledge

Every day, developers have hundreds of AI conversations that produce valuable code, insights, and decisions. But this knowledge disappears into chat history, leaving you to:

• Reinvent solutions you already figured out
• Debug without context of why code was written that way
• Miss patterns in what prompts actually work
• Lose traceability for compliance and code reviews

The Solution: Automatic Prompt History Records

PHRs are created automatically after every significant AI interaction in Spec Kit. No extra commands, no manual effort—just work normally and get complete documentation of your AI-assisted development journey.

Core Learning Science Principles

How It Works: Completely Automatic

Setup (One Time)

When you run specify init:

specify init --ai gemini  # Or claude, cursor, copilot, etc.

You automatically get:

• ✅ Implicit PHR creation built into every command
• ✅ PHR templates and scripts
• ✅ Deterministic location logic (pre-feature vs feature-specific)
• ✅ Manual /phr command for custom cases (optional)

Daily Usage: Just Work Normally

PHRs are created automatically after:

/constitution Define quality standards     → PHR created in docs/prompts/
/specify Create authentication feature     → PHR created in docs/prompts/
/plan Design JWT system                    → PHR created in specs/001-auth/prompts/
/tasks Break down implementation           → PHR created in specs/001-auth/prompts/
/implement Write JWT token generation      → PHR created in specs/001-auth/prompts/

Also after general work:

• Technical questions producing code → PHR created
• Debugging or fixing errors → PHR created
• Code explanations → PHR created
• Refactoring → PHR created

You see: Brief confirmation like 📝 PHR-0003 recorded

That's it! Keep working, and your knowledge compounds automatically.

Deterministic PHR Location Strategy

PHRs use a simple, deterministic rule for where they're stored:

Before Feature Exists (Pre-Feature Work)

Location: docs/prompts/
Stages: constitution, spec
Naming: 0001-title.constitution.prompt.md

Use cases:

• Creating constitution.md
• Writing initial specs

Example:

docs/
└── prompts/
    ├── 0001-define-quality-standards.constitution.prompt.md
    └── 0002-create-auth-spec.spec.prompt.md

Note: The general stage can also fall back to docs/prompts/ if no specs/ directory exists, but will show a warning suggesting to use constitution or spec stages instead, or create a feature first.

After Feature Exists (Feature Work)

Location: specs/<feature>/prompts/
Stages: architect, red, green, refactor, explainer, misc, general
Naming: 0001-title.architect.prompt.md

Use cases:

• Feature planning and design
• Implementation work
• Debugging and fixes
• Code refactoring
• General feature work

Example:

specs/
├── 001-authentication/
│   ├── spec.md
│   ├── plan.md
│   └── prompts/
│       ├── 0001-design-jwt-system.architect.prompt.md
│       ├── 0002-implement-jwt.green.prompt.md
│       ├── 0003-fix-token-bug.red.prompt.md
│       └── 0004-setup-docs.general.prompt.md
└── 002-database/
    └── prompts/
        ├── 0001-design-schema.architect.prompt.md
        └── 0002-optimize-queries.refactor.prompt.md

Key Features

• Local sequence numbering: Each directory starts at 0001
• Stage-based extensions: Files show their type (.architect.prompt.md, .red.prompt.md)
• Auto-detection: Script finds the right feature from branch name or latest numbered feature
• Clear location rules:
  • constitution, spec → always docs/prompts/
  • Feature stages → specs/<feature>/prompts/
  • general → feature context if available, else docs/prompts/ with warning

PHR Stages

Pre-Feature Stages

Feature-Specific Stages (TDD Cycle)

Note: general stage behavior:

• If specs/ exists: goes to specs/<feature>/prompts/
• If no specs/: falls back to docs/prompts/ with warning

What Happens Behind the Scenes

Automatic PHR Creation Flow

When you run any significant command:

1. You execute work - /constitution, /specify, /plan, debugging, etc.
2. AI completes the task - Creates files, writes code, fixes bugs
3. Stage auto-detected - System determines: architect, green, red, refactor, etc.
4. PHR auto-created - File generated with proper naming and location
5. Brief confirmation - You see: 📝 PHR-0003 recorded

All metadata captured automatically:

• Full user prompt (complete multiline text)
• Response summary
• Files modified
• Tests run
• Stage and feature context
• Timestamps and user info

Integrated SDD Workflow

/constitution → PHR created (docs/prompts/)
     ↓
/specify → PHR created (docs/prompts/)
     ↓
/plan → PHR created (specs/<feature>/prompts/) + ADR suggestion
     ↓
/tasks → PHR created (specs/<feature>/prompts/)
     ↓
/implement → PHR created (specs/<feature>/prompts/)
     ↓
Debug/fix → PHR created (specs/<feature>/prompts/)
     ↓
Refactor → PHR created (specs/<feature>/prompts/)

PHRs compound throughout the entire workflow—automatically.

Integration with SDD Components

• PHRs Link to Everything

links:
  spec: specs/001-auth/spec.md # Feature spec
  adr: docs/adr/0003-jwt-choice.md # Architectural decision
  ticket: JIRA-123 # Issue tracker
  pr: https://github.com/org/repo/pull/45 # Pull request

• Workflow Integration

1. /constitution   → docs/prompts/0001-quality-standards.constitution.prompt.md
2. /specify        → docs/prompts/0002-auth-requirements.spec.prompt.md
3. /plan           → specs/001-auth/prompts/0001-design-system.architect.prompt.md
4. /adr            → (ADR references the PHR for context)
5. /tasks          → specs/001-auth/prompts/0002-break-down-tasks.architect.prompt.md
6. /implement      → specs/001-auth/prompts/0003-implement-jwt.green.prompt.md
7. Debug & fix     → specs/001-auth/prompts/0004-fix-token-bug.red.prompt.md
8. Refactor        → specs/001-auth/prompts/0005-extract-middleware.refactor.prompt.md

Why This Works (Learning Science)

• Spaced Repetition:

• Weekly PHR reviews reinforce successful prompting patterns

• Searching past PHRs when facing similar problems builds retrieval strength

• Pattern recognition emerges from reviewing your own prompt history

• Metacognition:

• Reflection prompts in each PHR force you to think about what worked

• "Next prompts" section helps you plan follow-up actions

• Outcome tracking shows the connection between prompts and results

• Interleaving:

• Stage tagging (architect/red/green) mixes different types of thinking

• Context switching between planning, coding, and debugging strengthens transfer

• Cross-domain learning happens when you apply patterns from one area to another

• Retrieval Practice:

• Searching PHRs forces active recall of past solutions

• Weekly reviews strengthen memory consolidation

• Reapplying patterns to new problems deepens understanding

Troubleshooting

"Feature stage 'architect' requires specs/ directory and feature context"

• Cause: Using feature stage (architect, red, green, etc.) before specs/ directory exists
• Solution: Use pre-feature stages (constitution, spec) or create a feature first with /specify

"No feature specified and no numbered features found"

• Cause: Working in feature context but no features exist
• Solution: Run /specify to create your first feature, or specify --feature manually

"Feature directory not found"

• Cause: Specified feature doesn't exist in specs/
• Solution: Check available features with ls specs/ or create the feature with /specify

"Warning: No specs/ directory found. Using docs/prompts/ for general stage."

• Cause: Using general stage when no specs/ directory exists
• Not an error: PHR will be created in docs/prompts/ as fallback
• Suggestion: Consider using constitution or spec stages for pre-feature work, or create a feature first

Comparison: PHR vs Traditional Methods

Summary: PHRs are Automatic

PHRs are built into Spec Kit with automatic creation:

✅ Completely automatic: Created after every significant command—no extra work
✅ Deterministic location:

• Pre-feature (constitution, spec) → docs/prompts/
• Feature work → specs/<feature>/prompts/
• Clear file naming with stage extensions

✅ Full metadata capture: Prompts, responses, files, tests, timestamps
✅ Stage-based organization: architect, red, green, refactor, explainer, etc.
✅ Learning-focused: Based on spaced repetition and retrieval practice
✅ Team-friendly: Version-controlled, searchable, shareable
✅ Compliance-ready: Complete audit trail with no manual effort

Start using PHRs today by running specify init and working normally. Every AI interaction is automatically captured, documented, and searchable. Your future self (and your team) will thank you! 🚀

Key Takeaway

You don't need to think about PHRs—they just happen.
Work normally with Spec Kit commands, and get automatic documentation of your entire AI-assisted development journey.