Prompt History Records (PHRs)
📖 Complete Development History
Every interaction with Claude Code during textbook development is documented here as Prompt History Records (PHRs). These records provide complete transparency into how this book was built.
Total PHRs: 17 (and counting!)
🎯 What is a PHR?
A Prompt History Record captures:
- User Input: The exact prompt or command
- AI Response: Key decisions and actions taken
- Files Changed: What was created or modified
- Outcome: Success criteria and results
- Stage: Which part of the workflow (spec/plan/tasks/implement)
Why PHRs Matter:
- ✅ Reproducibility: Anyone can recreate the process
- ✅ Learning: See how AI-assisted development works
- ✅ Auditability: Full trail of decisions
- ✅ Collaboration: New contributors understand context
- ✅ Quality: Ensure process was followed correctly
📚 PHRs by Chapter
Chapter 1: Introduction to Physical AI
Total: 9 PHRs | Status: ✅ Complete
| ID | Title | Stage | Date | Link |
|---|---|---|---|---|
| 001 | Create intro chapter spec | Spec | 2025-11-28 | View |
| 002 | Create intro chapter plan | Plan | 2025-11-28 | View |
| 003 | Create intro chapter tasks | Tasks | 2025-11-28 | View |
| 004 | Implement intro chapter MVP | Implement | 2025-11-28 | View |
| 005 | Implement intro chapter US2 | Implement | 2025-11-28 | View |
| 006 | Implement intro chapter US3 | Implement | 2025-11-28 | View |
| 007 | Implement intro chapter US4 | Implement | 2025-11-28 | View |
| 008 | Implement assessments phase7 | Implement | 2025-11-28 | View |
| 009 | Polish final validation phase8 | Implement | 2025-11-28 | View |
Highlights:
- Complete /sp.specify → /sp.plan → /sp.tasks → /sp.implement cycle
- 8 implementation phases (MVP → US2 → US3 → US4 → Assessments → Polish)
- Result: 1975-line comprehensive introduction chapter
- All acceptance criteria met
Key Learnings:
- Modular user stories (US1-US4) enable incremental implementation
- Polish phase caught formatting inconsistencies
- Validation report confirms constitution compliance
Related ADRs:
- ADR-001: Docusaurus for Textbook Delivery - Platform choice for deploying chapter content
- ADR-007: Mermaid for Architecture Diagrams - Diagramming approach used in chapter
Chapter 2: ROS 2 Fundamentals
Total: 3 PHRs | Status: 🟡 22% Complete (foundation only)
| ID | Title | Stage | Date | Link |
|---|---|---|---|---|
| 001 | Create ros2 fundamentals spec | Spec | 2025-11-28 | View |
| 002 | Create ros2 fundamentals tasks | Tasks | 2025-11-28 | View |
| 003 | Implement ros2 fundamentals foundation | Implement | 2025-11-29 | View |
Highlights:
- 65 tasks generated (14 complete, 51 remaining)
- Foundation content complete: objectives, overview, diagrams, quiz, troubleshooting
- 4 labs planned (P1: Pub/Sub, P2: Services/Actions, P3: Parameters/Launch, P4: Transforms)
- TODO.md tracks remaining work transparently
What's Done:
- ✅ Learning objectives (5 measurable goals)
- ✅ Conceptual overview with ROS 2 graph architecture
- ✅ Communication patterns flowchart (Mermaid)
- ✅ Node lifecycle diagram (Mermaid)
- ✅ Troubleshooting guide (10 common errors)
- ✅ Quiz with 10 conceptual questions
- ✅ Glossary with 20+ ROS 2 terms
What's Remaining:
- ⏳ Lab P1: Pub/Sub (publisher_node.py, subscriber_node.py, launch file)
- ⏳ Lab P2: Services & Actions (IK server, pick/place action server)
- ⏳ Lab P3: Parameters & Launch (configurable nodes, multi-node systems)
- ⏳ Lab P4: Transforms (broadcaster, listener, humanoid tf2 tree)
- ⏳ Assessment rubrics and answer keys
Related ADRs:
- ADR-003: ROS 2 Humble as Primary Distribution - ROS 2 version used in all code examples
- ADR-004: Multi-Simulation Strategy - Gazebo used for labs in this chapter
- ADR-005: Assessment Methodology - Lab grading structure defined
- ADR-007: Mermaid for Architecture Diagrams - Node graph and lifecycle diagrams
Chapter 3: Simulation Environments
Total: 3 PHRs | Status: 🚧 Planned (awaiting implementation)
| ID | Title | Stage | Date | Link |
|---|---|---|---|---|
| 001 | Chapter 3 simulation spec | Spec | 2025-11-28 | View |
| 002 | Chapter 3 simulation plan | Plan | 2025-11-28 | View |
| 003 | Chapter 3 simulation tasks | Tasks | 2025-11-28 | View |
Ready for: /sp.implement when time permits
Planned Content:
- Gazebo Classic setup and world design
- Unity ML-Agents integration
- NVIDIA Isaac Sim basics
- Cross-platform simulation strategies
Related ADRs:
- ADR-003: ROS 2 Humble as Primary Distribution - Integration with ROS 2 Humble
- ADR-004: Multi-Simulation Strategy - Key ADR: Multi-platform approach (Gazebo, Isaac, Unity)
- ADR-007: Mermaid for Architecture Diagrams - Simulation pipeline diagrams
Chapter 4: Perception Systems
Total: 1 PHR | Status: 🚧 Spec Only
| ID | Title | Stage | Date | Link |
|---|---|---|---|---|
| 001 | Chapter 4 perception spec | Spec | 2025-11-28 | View |
Next Steps: /sp.plan → /sp.tasks → /sp.implement
General / Infrastructure
Total: 1 PHR
| ID | Title | Stage | Date | Link |
|---|---|---|---|---|
| 001 | Commit chapter1 setup git | General | 2025-11-28 | View |
📊 PHR Statistics
By Stage
- Spec: 4 PHRs (23.5%)
- Plan: 2 PHRs (11.8%)
- Tasks: 3 PHRs (17.6%)
- Implement: 7 PHRs (41.2%)
- General: 1 PHR (5.9%)
By Chapter
- Chapter 1: 9 PHRs (Complete workflow)
- Chapter 2: 3 PHRs (Partial workflow)
- Chapter 3: 3 PHRs (Spec → Plan → Tasks)
- Chapter 4: 1 PHR (Spec only)
- General: 1 PHR (Infrastructure)
Completion Rate
- Chapters with Full Workflow: 1/10 (10%)
- Chapters with Specs: 4/10 (40%)
- Chapters with Plans: 3/10 (30%)
- Chapters with Tasks: 3/10 (30%)
- Chapters with Implementation: 2/10 (20% - Ch1 complete, Ch2 partial)
🔍 How to Read a PHR
Every PHR follows this structure:
---
id: 004
title: "Implement intro chapter MVP"
stage: implement
date: 2025-11-28
surface: agent
model: claude-sonnet-4-5
feature: 001-intro-physical-ai
branch: 001-intro-physical-ai
command: /sp.implement
labels: ["mvp", "chapter1", "foundation"]
links:
spec: specs/001-intro-physical-ai/spec.md
ticket: null
adr: null
pr: null
files:
- chapters/01-introduction-physical-ai/README.md
- chapters/01-introduction-physical-ai/assets/glossary.md
tests:
- Manual validation against acceptance criteria
---
## Prompt
User requested: "Implement the MVP for Chapter 1 (US1: Foundation)"
## Response
[Detailed implementation steps...]
## Outcome
✅ Success
- Created comprehensive README.md (1500+ lines)
- Added glossary with 25+ terms
- All acceptance criteria met
Key Fields:
- ID: Sequential number within feature
- Stage: Which part of workflow (spec/plan/tasks/implement)
- Feature: Which chapter or component
- Files: What was created/modified
- Outcome: Success/failure and details
🎯 PHR Best Practices
For Contributors
- Read PHRs Before Starting: Understand what's been done
- Follow Same Pattern: Use /sp.* commands consistently
- Check Related PHRs: See how similar tasks were handled
- Link PHRs in Commits: Reference PHR ID for traceability
For Reviewers
- Verify PHR Exists: Every major change should have one
- Check Files List: Ensure all changed files are documented
- Validate Outcome: Did acceptance criteria pass?
- Review Stage Flow: Did spec → plan → tasks → implement happen?
For Learners
- Study Complete Workflows: Start with Chapter 1 (9 PHRs)
- Compare Stages: See how spec translates to plan, then tasks
- Analyze Decisions: Why were certain approaches chosen?
- Reproduce Process: Try creating your own chapter following same pattern
🔗 Related Resources
- Spec-Driven Workflow: Understand the /sp.* command process
- ADR Index: See architectural decisions referenced in PHRs
- Constitution: Quality standards all PHRs must follow
- GitHub Repository: Browse PHRs directly
📈 Live Updates
This gallery is updated automatically as new PHRs are created. Latest additions appear at the top of each chapter section.
Last Updated: 2025-11-29 Next PHR Expected: Chapter 2 Lab Implementation or Chapter 3 Implementation Recent Updates: Added ADR references linking PHRs to architectural decisions
💬 Feedback
Found an issue with a PHR or have questions about the process?
- Open an issue: GitHub Issues
- Reference the PHR ID for faster resolution
This gallery demonstrates the complete transparency of spec-driven development. Every decision, every change, fully documented.