# Documentation Templates

Detailed templates for each file in the /docs structure.

## 00-context/blueprint.md

```markdown
# [Project Name] Blueprint

## Identity
[What this project IS in 2-3 sentences. Sourced from README.]

## Status
| Area | Status | Notes |
|------|--------|-------|
| [feature/module] | implemented / in-progress / planned | [brief] |

## Architecture
[High-level structure: packages, modules, entry points. Tables or flat lists, no ASCII trees.]

## Implemented
[What works today. Group by feature area. Be specific about what ships.]

## Planned
[What's next. Ordered by priority. Link to design docs if they exist.]

## Future Direction
[Where does this project want to be? North star. 3-5 bullets max.]

## Key Decisions
[Major architectural choices already made. Brief rationale. Link to decisions-log if available.]
```

## 00-context/vision.md

```markdown
# Vision

## Problem
[What problem does this solve? Who feels the pain?]

## Solution
[How does this product solve it?]

## Target Users
[Who is this for? Primary/secondary personas]

## Boundaries
### In Scope
- [Feature/capability 1]
- [Feature/capability 2]

### Out of Scope
- [What we explicitly won't do]
- [Adjacent problems we're ignoring]

## Success Metrics
- [Metric 1: how measured]
- [Metric 2: how measured]
```

## 00-context/assumptions.md

```markdown
# Assumptions & Risks

## Technical Assumptions
- [Assumption 1: e.g., "Users have Python 3.8+"]
- [Assumption 2: e.g., "API response time < 200ms"]

## Business Assumptions
- [Assumption 1: e.g., "Users prefer CLI over GUI"]
- [Assumption 2: e.g., "10K users within 6 months"]

## Known Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk description] | High/Med/Low | [How we handle it] |

## Open Questions
- [ ] [Question 1 that needs answering]
- [ ] [Question 2 that blocks decisions]
```

## 00-context/system-state.md

```markdown
# System State

## What's Implemented
### Core Features
- [Feature 1] - Status: ✅ Live | 🚧 In Progress | 📋 Planned
- [Feature 2] - Status: [...]

### Tech Stack
- Language: [e.g., Python 3.11]
- Frameworks: [e.g., FastAPI, React]
- Database: [e.g., PostgreSQL 15]
- Infrastructure: [e.g., AWS, Docker]

## What's In Progress
- [Feature/change being worked on]
- [Expected completion: rough timeframe]

## What's Planned
- [Next feature to build]
- [Roadmap item 2]

## Known Issues
- [Issue 1: description, severity]
- [Issue 2: description, severity]
```

## 01-product/prd.md

```markdown
# Product Requirements Document

## Problem Statement
[Clear description of problem. 2-3 paragraphs max.]

## User Personas
### Primary: [Persona Name]
- **Who**: [Role/description]
- **Pain**: [Current problem]
- **Goal**: [What they want to achieve]

### Secondary: [Persona Name]
[Same structure]

## Features
### Must Have (P0)
1. **[Feature name]**
   - Description: [What it does]
   - User value: [Why it matters]
   - Acceptance: [How we know it's done]

### Should Have (P1)
[Same structure]

### Nice to Have (P2)
[Same structure]

## Non-Functional Requirements
- Performance: [e.g., "API responds < 200ms p95"]
- Security: [e.g., "OAuth2, encrypted at rest"]
- Scalability: [e.g., "Handle 10K concurrent users"]
- Reliability: [e.g., "99.9% uptime"]

## Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]

## Out of Scope
- [Explicitly excluded feature 1]
- [Explicitly excluded feature 2]
```

## 02-features/feature-<name>/feature-spec.md

```markdown
# Feature: [Name]

## User Intent
**As a** [user type]
**I want to** [action]
**So that** [benefit]

## User Stories
1. **Story 1**: [Description]
   - Acceptance: User can [specific action]
   - Acceptance: System responds with [expected behavior]

## Acceptance Criteria
- [ ] [Criterion 1: testable condition]
- [ ] [Criterion 2: testable condition]
- [ ] [Criterion 3: testable condition]

## Edge Cases
- **Case 1**: [Scenario] → [Expected behavior]
- **Case 2**: [Scenario] → [Expected behavior]

## UI/UX Notes
[Wireframes, mockups, or interaction descriptions]
```

## 02-features/feature-<name>/tech-design.md

```markdown
# Technical Design: [Feature Name]

## Architecture Approach
[High-level approach. Diagram if helpful.]

## Components
### [Component 1]
- **Responsibility**: [What it does]
- **Interface**: [API/methods]
- **Dependencies**: [What it needs]

### [Component 2]
[Same structure]

## Data Models
```language
[Schema/types/interfaces]
```

## APIs
### Endpoint: `METHOD /path`
- **Request**: [Schema]
- **Response**: [Schema]
- **Errors**: [Error codes]

## Security Considerations
- [Auth/authz requirements]
- [Data validation]
- [Potential vulnerabilities addressed]

## Performance Considerations
- [Expected load]
- [Optimization strategy]
- [Caching approach]

## Trade-offs
- **Decision**: [What we chose]
- **Alternatives**: [What we didn't choose]
- **Rationale**: [Why]
```

## 02-features/feature-<name>/dev-tasks.md

```markdown
# Development Tasks: [Feature Name]

## Tasks
- [ ] Task 1: [Specific, executable action]
  - Dependencies: [What must be done first]
  - Files: [Which files to touch]
- [ ] Task 2: [...]
- [ ] Task 3: [...]

## Implementation Notes
[Context LLM needs to execute tasks]

## Definition of Done
- [ ] Code complete
- [ ] Tests pass
- [ ] Docs updated
- [ ] Reviewed
```

## 02-features/feature-<name>/test-plan.md

```markdown
# Test Plan: [Feature Name]

## Test Strategy
- **Unit**: [What to unit test]
- **Integration**: [What to integration test]
- **E2E**: [What to E2E test]

## Test Cases
### TC-1: [Test name]
- **Given**: [Precondition]
- **When**: [Action]
- **Then**: [Expected result]

### TC-2: [Test name]
[Same structure]

## Edge Cases
- [ ] Test: [Edge case 1]
- [ ] Test: [Edge case 2]

## Performance Tests
- [ ] Load test: [Scenario]
- [ ] Stress test: [Scenario]

## Security Tests
- [ ] Auth test: [Scenario]
- [ ] Input validation: [Scenario]
```

## 03-logs/implementation-log.md

```markdown
# Implementation Log

Track what changed in code and why.

## YYYY-MM-DD - [Change Title]
**What**: [Code changes made - files, functions, modules]
**Why**: [Business/technical reason for change]
**Impact**: [What changed for users/devs]
**Ref**: [PR/commit/issue reference]

---

## YYYY-MM-DD - [Change Title]
[Repeat structure]
```

## 03-logs/decisions-log.md

```markdown
# Decisions Log

Track architectural and product decisions.

## YYYY-MM-DD - [Decision Title]
**Context**: [Why this decision needed]
**Options Considered**:
1. Option A: [Description, pros/cons]
2. Option B: [Description, pros/cons]

**Decision**: [What we chose]
**Rationale**: [Why we chose it]
**Consequences**: [Implications, trade-offs]
**Ref**: [Discussion link, RFC number]

---

## YYYY-MM-DD - [Decision Title]
[Repeat structure]
```

## 03-logs/bug-log.md

```markdown
# Bug Log

Track bugs, root causes, fixes.

## [BUG-001] - [Bug Title]
**Reported**: YYYY-MM-DD
**Severity**: Critical | High | Medium | Low
**Symptoms**: [What users saw]
**Root Cause**: [What went wrong technically]
**Fix**: [How resolved]
**Prevention**: [How we avoid repeating]
**Ref**: [Issue/PR reference]

---

## [BUG-002] - [Bug Title]
[Repeat structure]
```

## 03-logs/validation-log.md

```markdown
# Validation Log

Track what happened after shipping.

## YYYY-MM-DD - [Release/Feature Name]
**Validated**: [What was tested in production]
**Results**:
- Metric 1: [Actual vs expected]
- Metric 2: [Actual vs expected]

**Issues Found**: [Problems discovered post-ship]
**User Feedback**: [What users said]
**Next Steps**: [Follow-up actions]

---

## YYYY-MM-DD - [Release/Feature Name]
[Repeat structure]
```

## 03-logs/insights.md

```markdown
# Insights

Learnings and future improvements.

## What Worked Well
- [Success 1: what and why]
- [Success 2: what and why]

## What Didn't Work
- [Issue 1: what went wrong, how to improve]
- [Issue 2: what went wrong, how to improve]

## Process Improvements
- [ ] [Change we should make to workflow]
- [ ] [Tool/practice to adopt]

## Technical Debt
- [ ] [Debt item 1: what, impact, effort to fix]
- [ ] [Debt item 2: what, impact, effort to fix]

## Future Optimizations
- [Optimization opportunity 1]
- [Optimization opportunity 2]
```

## 04-process/dev-workflow.md

```markdown
# Development Workflow

## Daily Dev Loop

### 1. Pick Task
- Check `02-features/*/dev-tasks.md` or backlog
- Verify acceptance criteria clear

### 2. Implement
- Write test first (if TDD)
- Implement feature
- Run tests locally
- Update docs

### 3. Review
- Self-review checklist:
  - [ ] Tests pass
  - [ ] Docs updated
  - [ ] No console.logs/debugs
  - [ ] Security reviewed
- Create PR

### 4. Ship
- Merge after approval
- Update `03-logs/implementation-log.md`
- Monitor production

## Branch Strategy
- `main`: production-ready code
- `feature/*`: new features
- `fix/*`: bug fixes

## Working with LLMs
- Provide context: link to relevant docs
- Reference acceptance criteria from feature specs
- Ask to update logs after changes
- Request test generation

## Code Review Checklist
- [ ] Matches acceptance criteria
- [ ] Tests cover edge cases
- [ ] Docs updated
- [ ] No security issues
- [ ] Performance acceptable
```

## 04-process/definition-of-done.md

```markdown
# Definition of Done

## Code Complete
- [ ] Implements all acceptance criteria
- [ ] Passes all tests (unit, integration, e2e)
- [ ] No linter errors
- [ ] Code reviewed and approved
- [ ] Security reviewed (if touching auth/data)

## Documentation Complete
- [ ] Feature spec updated (if behavior changed)
- [ ] API docs updated (if APIs changed)
- [ ] README updated (if setup changed)
- [ ] Logs updated (implementation-log, decisions-log)

## Testing Complete
- [ ] Unit tests written and passing
- [ ] Integration tests written and passing
- [ ] Manual testing completed
- [ ] Edge cases tested
- [ ] Performance acceptable

## Release Ready
- [ ] Deployed to staging
- [ ] Smoke tests pass
- [ ] Rollback plan documented
- [ ] Monitoring in place
```

## 04-process/llm-prompts.md

```markdown
# Canonical LLM Prompts

Standard prompts for documentation tasks.

## Create Feature Spec
\`\`\`
As backlog-manager, create a feature spec for [feature name] in 02-features/feature-[name]/.

Requirements:
[Paste requirements]

Include:
- User stories with acceptance criteria
- Edge cases
- UI/UX considerations
\`\`\`

## Create Technical Design
\`\`\`
As architect, create technical design for [feature name] in 02-features/feature-[name]/.

Feature spec: 02-features/feature-[name]/feature-spec.md

Include:
- Architecture approach
- Components and data models
- APIs
- Security and performance considerations
- Trade-offs
\`\`\`

## Generate Dev Tasks
\`\`\`
As 2-generate-tasks, break down the feature into executable dev tasks.

Feature spec: 02-features/feature-[name]/feature-spec.md
Tech design: 02-features/feature-[name]/tech-design.md

Create: 02-features/feature-[name]/dev-tasks.md
\`\`\`

## Update Implementation Log
\`\`\`
Update 03-logs/implementation-log.md with today's changes.

Changes made:
[Describe changes]

Why:
[Reason]

Impact:
[User/developer impact]
\`\`\`

## Update Decisions Log
\`\`\`
Update 03-logs/decisions-log.md with architectural decision.

Decision: [What we decided]
Context: [Why decision needed]
Options: [Alternatives considered]
Rationale: [Why we chose this]
\`\`\`
```

## docs/README.md

```markdown
# Documentation Guide

## Structure

Our docs follow a 5-tier hierarchy:

- **00-context/**: WHY this exists, WHAT's currently built
- **01-product/**: WHAT we must build (requirements)
- **02-features/**: HOW features are designed and built
- **03-logs/**: MEMORY of changes, decisions, bugs over time
- **04-process/**: HOW to work (workflows, standards)

## Quick Navigation

**Start here**: `00-context/vision.md` - understand product purpose
**Requirements**: `01-product/prd.md` - single source of truth
**Feature work**: `02-features/feature-*/` - specs, designs, tasks
**History**: `03-logs/` - what changed and why
**Workflows**: `04-process/` - how we work daily

## For Developers

1. **Starting new feature**:
   - Read: `01-product/prd.md` for requirements
   - Check: `02-features/` for existing feature patterns
   - Create: `02-features/feature-<name>/` with 4 files

2. **Daily work**:
   - Follow: `04-process/dev-workflow.md`
   - Check: `04-process/definition-of-done.md` before PR

3. **After changes**:
   - Update: `03-logs/implementation-log.md`
   - Update: `03-logs/decisions-log.md` if architectural

## For LLMs

Standard prompts: `04-process/llm-prompts.md`
Context loading: Start with `00-context/`, then drill into specific features

## Legacy Docs

[If existing docs/ subdirs exist, map them here]
- Old `commands/` → See `02-features/cli/`
- Old `development/` → See `04-process/dev-workflow.md`
- Old `guides/` → Distributed across `02-features/`
- Old `reference/` → See `00-context/` and `01-product/`
```