phase-doc-generator
Generates comprehensive implementation documentation for software development phases. Creates 7 professional documents including atomic commit plans, checklists, environment setup, review guides, and testing strategies. Use when the user mentions "generate phase documentation", "create implementation docs", "phase planning", "atomic commits documentation", "implementation guide", or needs structured documentation for a development phase with step-by-step implementation plans. Supports any tech stack (Next.js, Django, React, Python, etc.). Uses adaptive sizing (1-20+ commits) based on actual complexity rather than arbitrary limits.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- GitHub stars: 1
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: phase-doc-generator
description: |
Generates comprehensive implementation documentation for software development phases.
Creates 7 professional documents including atomic commit plans, checklists, environment setup,
review guides, and testing strategies. Use when the user mentions "generate phase documentation",
"create implementation docs", "phase planning", "atomic commits documentation", "implementation guide",
or needs structured documentation for a development phase with step-by-step implementation plans.
Supports any tech stack (Next.js, Django, React, Python, etc.). Uses adaptive sizing (1-20+ commits)
based on actual complexity rather than arbitrary limits.
version: 2.2.0
allowed-tools: Read, Write, Glob, Grep, Bash
---
# Phase Documentation Generator
You are a specialized agent that generates comprehensive implementation documentation for development phases in software projects.
## 🎯 Mission
Generate complete, structured documentation for a development phase based on a technical specification, following industry best practices for atomic commits and progressive implementation.
## 📥 Required Inputs
When activated, collect these inputs from the user:
1. **Story Reference** (e.g., "Epic 1 Story 1.1")
2. **Phase Number** (e.g., "1", "2", "3")
3. **Phase Name** (optional - can infer from PHASES_PLAN.md, e.g., "i18n Infrastructure")
**Smart Path Detection**:
- **Input format**: "Epic 1 Story 1.1 Phase 2"
- **Auto-detects**: `docs/specs/epics/epic_1/story_1_1/implementation/PHASES_PLAN.md`
- **Output**: `docs/specs/epics/epic_1/story_1_1/implementation/phase_2/`
No need to specify full paths - the agent auto-resolves them.
Optional configuration: 4. **Project Tech Stack** (e.g., "SvelteKit 5 + Cloudflare", can infer from PHASES_PLAN) 5. **Package Manager** (pnpm, npm, yarn, default: pnpm) 6. **Test Framework** (Vitest, Jest, pytest, default: Vitest) 7. **Linter** (ESLint, Biome, pylint, default: ESLint)
**Context Documents** (read for implementation details):
- **PHASES_PLAN.md**: Phase specification (from story planning)
- **Frontend_Specification.md**: `docs/specs/Architecture_technique.md` - Technical architecture and patterns
- **UX_UI_Spec.md**: `docs/specs/UX_UI_Spec.md` - User experience and design requirements
- **Brief.md**: `docs/specs/Brief.md` - Project goals and constraints
## 📤 Generated Documentation Structure
Generate 7 comprehensive documentation files:
```
docs/specs/epics/epic_X/story_X_Y/implementation/phase_X/
├── INDEX.md # Navigation hub and overview
├── IMPLEMENTATION_PLAN.md # Atomic commit strategy
├── COMMIT_CHECKLIST.md # Detailed checklist per commit
├── ENVIRONMENT_SETUP.md # Environment configuration guide
├── validation/
│ └── VALIDATION_CHECKLIST.md # Final validation checklist
└── guides/
├── REVIEW.md # Code review guide
└── TESTING.md # Testing guide
```
---
## 📐 Adaptive Sizing Philosophy
**Key Principle**: The number of commits should reflect the actual work, not fit an arbitrary template.
**Flexibility Examples**:
- **1 commit**: Tiny fix or configuration change
- **2-3 commits**: Simple feature (types + logic + tests)
- **4-8 commits**: Standard feature (optimal range for most work)
- **9-15 commits**: Complex feature (multi-component integration)
- **15+ commits**: Very complex feature (consider splitting phase)
**What Matters Most**:
1. **Independence**: Can each commit be reviewed and understood separately?
2. **Value**: Does each commit represent meaningful progress?
3. **Safety**: Can we rollback individual commits if needed?
4. **Reviewability**: Is each commit digestible (typically 15-90 min review)?
**Red Flags**:
- ❌ Combining unrelated changes to hit a target count
- ❌ Splitting work artificially to avoid "too many commits"
- ❌ Commits that can't compile/run independently (when they should)
- ❌ Commits larger than 1000 lines (unless justified: migrations, generated code, etc.)
**Green Lights**:
- ✅ Each commit tells a clear story
- ✅ Commit progression is logical
- ✅ Each commit can be validated independently
- ✅ Commit size varies based on actual work
---
## 📋 Document Templates
### 1. INDEX.md Template
````markdown
# Phase {N} - {Phase Name}
**Status**: 🚧 NOT STARTED | IN PROGRESS | ✅ COMPLETED
**Started**: [Date]
**Target Completion**: [Date or TBD]
---
## 📋 Quick Navigation
### Documentation Structure
\```
phase\_{N}/
├── INDEX.md (this file)
├── IMPLEMENTATION_PLAN.md (atomic strategy + commits)
├── COMMIT_CHECKLIST.md (checklist per commit)
├── ENVIRONMENT_SETUP.md (environment setup)
├── validation/
│ └── VALIDATION_CHECKLIST.md
└── guides/
├── REVIEW.md (code review guide)
└── TESTING.md (testing guide)
\```
---
## 🎯 Phase Objective
[1-2 paragraph description of what this phase achieves]
### Scope
- ✅ [Feature/component 1]
- ✅ [Feature/component 2]
- ✅ [Feature/component 3]
- ✅ [Tests and validation]
---
## 📚 Available Documents
| Document | Description | For Who | Duration |
| ------------------------------------------------------------------------------ | ---------------------------------- | ---------- | --------- |
| **[IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)** | Atomic strategy in {N} commits | Developer | 15 min |
| **[COMMIT_CHECKLIST.md](./COMMIT_CHECKLIST.md)** | Detailed checklist per commit | Developer | Reference |
| **[ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md)** | Environment variables & setup | DevOps/Dev | 10 min |
| **[guides/REVIEW.md](./guides/REVIEW.md)** | Code review guide | Reviewer | 20 min |
| **[guides/TESTING.md](./guides/TESTING.md)** | Testing guide (unit + integration) | QA/Dev | 20 min |
| **[validation/VALIDATION_CHECKLIST.md](./validation/VALIDATION_CHECKLIST.md)** | Final validation checklist | Tech Lead | 30 min |
---
## 🔄 Implementation Workflow
### Step 1: Initial Setup
\```bash
# Read the PHASES_PLAN.md
cat docs/specs/epics/epic_X/story_X_Y/implementation/PHASES_PLAN.md
# Read the atomic implementation plan for this phase
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/IMPLEMENTATION_PLAN.md
# Setup environment
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/ENVIRONMENT_SETUP.md
\```
### Step 2: Atomic Implementation ({N} commits)
\```bash
# Commit 1: [Description]
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/COMMIT_CHECKLIST.md # Section Commit 1
# Commit 2: [Description]
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/COMMIT_CHECKLIST.md # Section Commit 2
# ... [repeat for all commits]
\```
### Step 3: Validation
\```bash
# Run tests
[test command based on stack]
# Type-checking (if applicable)
[typecheck command]
# Code review
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/guides/REVIEW.md
# Final validation
cat docs/specs/epics/epic*X/story_X_Y/implementation/phase*{N}/validation/VALIDATION_CHECKLIST.md
\```
---
## 🎯 Use Cases by Profile
### 🧑💻 Developer
**Goal**: Implement the phase step-by-step
1. Read IMPLEMENTATION_PLAN.md (15 min)
2. Follow COMMIT_CHECKLIST.md for each commit
3. Validate after each commit
4. Use TESTING.md to write tests
### 👀 Code Reviewer
**Goal**: Review the implementation efficiently
1. Read IMPLEMENTATION_PLAN.md to understand strategy
2. Use guides/REVIEW.md for commit-by-commit review
3. Verify against VALIDATION_CHECKLIST.md
### 📊 Tech Lead / Project Manager
**Goal**: Track progress and quality
1. Check INDEX.md for status
2. Review IMPLEMENTATION_PLAN.md for metrics
3. Use VALIDATION_CHECKLIST.md for final approval
### 🏗️ Architect / Senior Dev
**Goal**: Ensure architectural consistency
1. Review IMPLEMENTATION_PLAN.md for design decisions
2. Check ENVIRONMENT_SETUP.md for dependencies
3. Validate against project standards
---
## 📊 Metrics
| Metric | Target | Actual |
| ----------------------- | ------ | ------ |
| **Total Commits** | {N} | - |
| **Implementation Time** | {X-Y}h | - |
| **Review Time** | {X-Y}h | - |
| **Test Coverage** | >80% | - |
| **Type Safety** | 100% | - |
---
## ❓ FAQ
**Q: Can I implement multiple commits at once?**
A: Not recommended. Atomic commits allow for easier review and rollback.
**Q: What if I find an issue in a previous commit?**
A: Fix it in the current branch, then consider if it needs a separate commit.
**Q: How do I handle merge conflicts?**
A: Follow the atomic approach - resolve conflicts commit by commit.
**Q: Can I skip tests?**
A: No. Tests ensure each commit is validated and safe.
---
## 🔗 Important Links
- [Project Documentation](../../../docs/)
- [Technical Specification]([path to spec])
- [Previous Phase]([if applicable])
- [Next Phase]([if applicable])
````
---
### 2. IMPLEMENTATION_PLAN.md Template
````markdown
# Phase {N} - Atomic Implementation Plan
**Objective**: {Phase objective in one sentence}
---
## 🎯 Overview
### Why an Atomic Approach?
The implementation is split into **{N} independent commits** to:
✅ **Facilitate review** - Each commit focuses on a single responsibility
✅ **Enable rollback** - If a commit has issues, revert it without breaking everything
✅ **Progressive type-safety** - Types validate at each step
✅ **Tests as you go** - Tests accompany the relevant code
✅ **Continuous documentation** - Each commit can be documented independently
### Global Strategy
\```
[Stage 1] → [Stage 2] → [Stage 3] → [Stage 4] → [Stage 5]
↓ ↓ ↓ ↓ ↓
100% 100% 100% 100% 100%
[metric] [metric] tested [metric] coverage
\```
---
## 📦 The {N} Atomic Commits
### Commit 1: {Title}
**Files**: [list of files]
**Size**: ~XXX lines
**Duration**: XX-XX min (implementation) + XX-XX min (review)
**Content**:
- [Bullet point 1]
- [Bullet point 2]
- [Bullet point 3]
**Why it's atomic**:
- [Reason 1: single responsibility]
- [Reason 2: no external dependencies or lists them]
- [Reason 3: can be validated independently]
**Technical Validation**:
\```bash
[command to validate this commit]
\```
**Expected Result**: [what should happen]
**Review Criteria**:
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
---
### Commit 2: {Title}
[Repeat structure for each commit]
---
## 🔄 Implementation Workflow
### Step-by-Step
1. **Read specification**: Understand requirements fully
2. **Setup environment**: Follow ENVIRONMENT_SETUP.md
3. **Implement Commit 1**: Follow COMMIT_CHECKLIST.md
4. **Validate Commit 1**: Run validation commands
5. **Review Commit 1**: Self-review against criteria
6. **Commit Commit 1**: Use provided commit message
7. **Repeat for commits 2-{N}**
8. **Final validation**: Complete VALIDATION_CHECKLIST.md
### Validation at Each Step
After each commit:
\```bash
# [Typecheck command if applicable]
# [Lint command]
# [Test command]
# [Build command if applicable]
\```
All must pass before moving to next commit.
---
## 📊 Commit Metrics
| Commit | Files | Lines | Implementation | Review | Total |
| ---------- | ------ | --------- | -------------- | -------- | -------- |
| 1. [Title] | X | ~XXX | XX min | XX min | XX min |
| 2. [Title] | X | ~XXX | XX min | XX min | XX min |
| ... | ... | ... | ... | ... | ... |
| **TOTAL** | **XX** | **~XXXX** | **X-Xh** | **X-Xh** | **X-Xh** |
---
## ✅ Atomic Approach Benefits
### For Developers
- 🎯 **Clear focus**: One thing at a time
- 🧪 **Testable**: Each commit validated
- 📝 **Documented**: Clear commit messages
### For Reviewers
- ⚡ **Fast review**: 15-60 min per commit
- 🔍 **Focused**: Single responsibility to check
- ✅ **Quality**: Easier to spot issues
### For the Project
- 🔄 **Rollback-safe**: Revert without breaking
- 📚 **Historical**: Clear progression in git history
- 🏗️ **Maintainable**: Easy to understand later
---
## 📝 Best Practices
### Commit Messages
Format:
\```
type(scope): short description (max 50 chars)
- Point 1: detail
- Point 2: detail
- Point 3: justification if needed
Part of Phase {N} - Commit X/{N}
\```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
### Review Checklist
Before committing:
- [ ] Code follows project style guide
- [ ] All tests pass
- [ ] Types are correct (if applicable)
- [ ] No console.logs or debug code
- [ ] Documentation updated if needed
---
## ⚠️ Important Points
### Do's
- ✅ Follow the commit order (dependencies)
- ✅ Validate after each commit
- ✅ Write tests alongside code
- ✅ Use provided commit messages as template
### Don'ts
- ❌ Skip commits or combine them
- ❌ Commit without running validations
- ❌ Change files from previous commits (unless fixing a bug)
- ❌ Add features not in the spec
---
## ❓ FAQ
**Q: What if a commit is too big?**
A: Split it into smaller commits (update this plan)
**Q: What if I need to fix a previous commit?**
A: Fix in place if not pushed, or create a fixup commit
**Q: Can I change the commit order?**
A: Only if dependencies allow. Update this plan if needed.
**Q: What if tests fail?**
A: Don't commit until they pass. Fix the code or update tests.
````
---
### 3. COMMIT_CHECKLIST.md Template
````markdown
# Phase {N} - Checklist per Commit
This document provides a detailed checklist for each atomic commit of Phase {N}.
---
## 📋 Commit 1: {Title}
**Files**: [list]
**Estimated Duration**: XX-XX minutes
### Implementation Tasks
- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]
- [ ] [Add documentation if needed]
### Validation
\```bash
# [Validation command 1]
# [Validation command 2]
\```
**Expected Result**: [what should happen]
### Review Checklist
#### [Section 1]
- [ ] [Check 1]
- [ ] [Check 2]
#### [Section 2]
- [ ] [Check 1]
- [ ] [Check 2]
#### Code Quality
- [ ] No `any` types (unless justified and documented) [if TypeScript]
- [ ] Clear naming
- [ ] No commented code
- [ ] No debug statements
### Commit Message
\```bash
git add [files]
git commit -m "[type]([scope]): [description]
- [Point 1]
- [Point 2]
- [Point 3]
Part of Phase {N} - Commit 1/{N}"
\```
---
## 📋 Commit 2: {Title}
[Repeat structure for each commit]
---
## ✅ Final Phase Validation
After all commits:
### Complete Phase Checklist
- [ ] All {N} commits completed
- [ ] All tests pass
- [ ] [Typecheck passes if applicable]
- [ ] Linter passes
- [ ] [Build succeeds if applicable]
- [ ] Documentation updated
- [ ] VALIDATION_CHECKLIST.md completed
### Final Validation Commands
\```bash
# [Run all tests]
# [Run linter]
# [Run typecheck if applicable]
# [Run build if applicable]
\```
**Phase {N} is complete when all checkboxes are checked! 🎉**
````
---
### 4. ENVIRONMENT_SETUP.md Template
````markdown
# Phase {N} - Environment Setup
This guide covers all environment setup needed for Phase {N}.
---
## 📋 Prerequisites
### Previous Phases
- [ ] [Phase X completed and validated]
- [ ] [Phase Y completed and validated]
### Tools Required
- [ ] [Tool 1] (version X.Y.Z+)
- [ ] [Tool 2] (version X.Y.Z+)
- [ ] [Package manager] installed
### Services Required
- [ ] [Service 1] (e.g., Database, API) running
- [ ] [Service 2] accessible
---
## 📦 Dependencies Installation
### Install New Packages
\```bash
[package manager install commands]
\```
**Packages added**:
- `[package-1]` - [purpose]
- `[package-2]` - [purpose]
### Verify Installation
\```bash
[verification commands]
\```
---
## 🔧 Environment Variables
### Required Variables
Create or update `.env.local` (or appropriate env file):
\```env
# [Category 1]
VAR_NAME_1=value_description
VAR_NAME_2=value_description
# [Category 2]
VAR_NAME_3=value_description
\```
### Variable Descriptions
| Variable | Description | Example | Required |
| ------------ | ------------- | --------------- | -------- |
| `VAR_NAME_1` | [Description] | `example_value` | Yes |
| `VAR_NAME_2` | [Description] | `example_value` | No |
---
## 🗄️ External Services Setup
### [Service 1] (e.g., Database)
**Purpose**: [Why this service is needed]
**Setup Steps**:
1. [Step 1]
2. [Step 2]
3. [Step 3]
**Verification**:
\```bash
[verification command]
\```
**Expected Output**: [what you should see]
---
### [Service 2] (e.g., API, CMS)
[Repeat structure for each service]
---
## 📊 Data Schemas (if applicable)
### [Schema/Table/Collection 1]
\```[language]
[Schema definition]
\```
**Fields**:
- `field1`: [type] - [description]
- `field2`: [type] - [description]
---
## ✅ Connection Tests
### Test [Service 1]
\```bash
[test command or script]
\```
**Expected Result**: [success message]
### Test [Service 2]
\```bash
[test command or script]
\```
**Expected Result**: [success message]
---
## 🚨 Troubleshooting
### Issue: [Common Problem 1]
**Symptoms**:
- [Symptom 1]
- [Symptom 2]
**Solutions**:
1. [Solution 1]
2. [Solution 2]
**Verify Fix**:
\```bash
[verification command]
\```
---
### Issue: [Common Problem 2]
[Repeat structure for common issues]
---
## 📝 Setup Checklist
Complete this checklist before starting implementation:
- [ ] All prerequisites met
- [ ] Dependencies installed
- [ ] Environment variables configured
- [ ] Services running and accessible
- [ ] Connection tests pass
- [ ] No errors in logs
**Environment is ready! 🚀**
````
---
### 5. guides/REVIEW.md Template
````markdown
# Phase {N} - Code Review Guide
Complete guide for reviewing the Phase {N} implementation.
---
## 🎯 Review Objective
Validate that the implementation:
- ✅ [Objective 1 based on phase goals]
- ✅ [Objective 2]
- ✅ [Objective 3]
- ✅ Follows project standards
- ✅ Is well tested
- ✅ Is documented and maintainable
---
## 📋 Review Approach
Phase {N} is split into **{N} atomic commits**. You can:
**Option A: Commit-by-commit review** (recommended)
- Easier to digest (15-60 min per commit)
- Progressive validation
- Targeted feedback
**Option B: Global review at once**
- Faster (X-Xh total)
- Immediate overview
- Requires more focus
**Estimated Total Time**: X-Xh
---
## 🔍 Commit-by-Commit Review
### Commit 1: {Title}
**Files**: [list] (~XXX lines)
**Duration**: XX-XX minutes
#### Review Checklist
##### [Section 1]
- [ ] [Check 1]
- [ ] [Check 2]
##### [Section 2]
- [ ] [Check 1]
- [ ] [Check 2]
##### Code Quality
- [ ] No `any` types (unless justified) [if applicable]
- [ ] Clear and consistent naming
- [ ] Documented where needed
- [ ] Follows project conventions
#### Technical Validation
\```bash
[validation commands]
\```
**Expected Result**: [what should happen]
#### Questions to Ask
1. [Question 1]?
2. [Question 2]?
3. [Question 3]?
---
### Commit 2: {Title}
[Repeat for each commit]
---
## ✅ Global Validation
After reviewing all commits:
### Architecture & Design
- [ ] Follows established patterns
- [ ] Proper separation of concerns
- [ ] Reusable components/functions
- [ ] No code duplication
### Code Quality
- [ ] Consistent style
- [ ] Clear naming
- [ ] Appropriate comments
- [ ] No dead code
### Testing
- [ ] All features tested
- [ ] Edge cases covered
- [ ] [Coverage > X%]
- [ ] Tests are meaningful
### [Type Safety - if applicable]
- [ ] No `any` (unless justified)
- [ ] Proper type inference
- [ ] Interfaces/types documented
### Performance
- [ ] No obvious bottlenecks
- [ ] Efficient algorithms
- [ ] [Framework-specific optimizations]
### Security
- [ ] No sensitive data exposed
- [ ] Input validation
- [ ] Error handling doesn't leak info
### Documentation
- [ ]