PWP Documentation Protocol

You are now operating under the Project Workflow Protocol's documentation discipline. Documentation is a living part of the codebase, not an afterthought.

Context: $ARGUMENTS

Phase 1: Identify Document Type

Determine which living document(s) need attention:

Document	Purpose	Update When
docs/VISION.md	Product roadmap, feature IDs	Adding/shipping features
docs/plans/README.md	Plan registry & status	Creating/completing plans
docs/plans/PLAN-*.md	Implementation details	During execution
CHANGELOG.md	Version history	Each release
docs/PRD.md	Requirements	Scope changes
docs/ARCHITECTURE.md	Tech stack & diagrams	System changes
README.md	Project overview	Setup/usage changes
CLAUDE.md	AI agent instructions	Pattern/convention changes

Phase 2: Feature Traceability

Use unique IDs to trace intent from vision to code:

Vision IDs:    A1, S1              (in VISION.md)
Plan IDs:      PLAN-001/P0         (in plan files)
Commits:       feat(PLAN-001/P0): description
Code Comments: // See PLAN-001/P2  (where non-obvious)

Traceability Chain

VISION.md (feature A1)
  → PLAN-003.md (implements A1)
    → commit: feat(PLAN-003/P1): add payment form
      → code comment: // See PLAN-003/P2 for validation rules

Every feature should be traceable from "why we're building it" to "where the code lives."

Phase 3: CHANGELOG Management

Follow Keep a Changelog format:

## [Unreleased]
### Added
- New payment processing module (PLAN-003)

### Changed
- Updated auth flow to support OAuth2 (PLAN-005)

### Fixed
- Cart total calculation rounding error (#142)

### Removed
- Legacy XML export endpoint (deprecated since v2.1)

Rules

• Group by: Added, Changed, Deprecated, Removed, Fixed, Security
• Reference plan IDs or issue numbers
• Write for humans, not machines
• Update with every meaningful PR, not just releases

Phase 4: Architecture Documentation

ARCHITECTURE.md should cover:

1. System Overview — High-level diagram of components
2. Tech Stack — Languages, frameworks, databases, infrastructure
3. Directory Structure — What lives where and why
4. Data Flow — How requests move through the system
5. Key Decisions — ADRs (Architecture Decision Records) for major choices
6. External Services — APIs, third-party integrations, auth providers

When to Update

• Adding a new service or database
• Changing the deployment architecture
• Introducing a new major dependency
• Modifying the authentication flow
• Restructuring the directory layout

Phase 5: Post-Completion Walkthroughs

After completing a major feature or plan, create a Walkthrough Artifact:

## Walkthrough: {Feature Name}

### What Changed
- {Design decisions made and rationale}
- {Key files added or modified}

### Verification
- {What was tested and how}
- {Edge cases covered}

### Evidence
- {Screenshots for UI changes}
- {Test output / coverage report}

### Follow-up
- {Known limitations}
- {Future work identified}
- {Technical debt introduced}

Phase 6: README Standards

A project README must include:

1. What it is — One sentence description
2. Quick start — How to run it locally in <5 commands
3. Prerequisites — Node version, env vars, services needed
4. Project structure — Brief directory overview
5. Available scripts — npm commands and what they do
6. Contributing — Link to CONTRIBUTING.md
7. License — Link to LICENSE

Documentation Anti-Patterns

Anti-Pattern	Why It's Wrong	Do This Instead
"Self-documenting code" as excuse	Complex systems need context code can't provide	Write docs for the why, code for the what
Stale docs	Worse than no docs — actively misleading	Update docs in the same PR as code changes
Documenting everything	Noise drowns signal	Document decisions, architecture, and non-obvious patterns
Separate doc repo	Falls out of sync immediately	Docs live next to the code they describe

Quick Checklist

• Correct document identified for the change
• Feature IDs trace from vision to code
• CHANGELOG updated with this release's changes
• Architecture docs reflect current system state
• README is accurate for new contributors
• No stale documentation left behind
• Walkthrough created for major features