docs-boy

# Docs-Boy: Project Documentation Skill

A comprehensive documentation skill that ensures consistent, well-structured project documentation with automated changelog generation and milestone tracking.

## Core Documentation Structure

Every project should have this structure in `/docs`:

```
/docs/
├── 01-System-Design.md        # Architecture overview
├── 02-Design-Patterns.md      # Patterns used in codebase
├── 03-Database-Design.md      # Schema and data models
├── 04-Tech-Stack.md           # Technologies and versions
├── 05-Project-Structure.md    # Directory organization
├── 06-API-Documentation.md    # API endpoints and contracts
├── 07-Setup-Installation.md   # Getting started guide
├── 08-Contribution-Guide.md   # How to contribute
├── 09-Design-System.md        # UI/UX guidelines
├── BRAND-GUIDELINES.md        # Brand identity (optional)
├── UPDATE-SUMMARY.md          # Latest changes summary
├── changelogs/
│   └── version-X.X.X.md       # Version history
└── milestone/
    └── feature-name/          # Active development tracking
```

---

## Workflow

### 1. Understand the Request

Identify what the user needs:
- **Create docs?** → Initialize full structure
- **Update docs?** → Analyze changes, update relevant files
- **Changelog?** → Generate from recent changes
- **Milestone?** → Create tracking plan
- **Pre-commit?** → Update UPDATE-SUMMARY and changelog
- **Audit?** → Check completeness against structure

### 2. Investigate Before Writing

**CRITICAL:** Always read the codebase before generating documentation.

1. **Check project type:**
   - `package.json` → Node.js/JavaScript
   - `requirements.txt` / `pyproject.toml` → Python
   - `Cargo.toml` → Rust
   - `go.mod` → Go

2. **Understand architecture:**
   - Read `README.md` for project overview
   - Check `src/` or `app/` for frontend structure
   - Check `server/`, `api/`, `backend/` for backend
   - Look at `docker-compose.yml`, `Dockerfile` for deployment

3. **Identify technologies:**
   - Check dependencies for frameworks (React, NestJS, etc.)
   - Look at config files (vite.config, tsconfig, etc.)
   - Note database schemas, API patterns

4. **Never invent or assume.** If something is unclear, ask the user.

### 3. Generate Documentation

Use templates from `references/templates.md` as starting points, but customize based on actual codebase findings.

### 4. Verify and Finalize

1. Re-read generated docs for accuracy
2. Ensure all file paths and code examples are correct
3. Check version numbers match `package.json` or equivalent
4. Verify no orphaned or outdated documentation

---

## Commands

| Command | Action |
|---------|--------|
| `docs init` | Initialize full docs structure for new project |
| `docs audit` | Check existing docs against required structure |
| `docs update` | Update docs based on recent code changes |
| `docs changelog` | Generate version changelog from recent changes |
| `docs milestone` | Create/update milestone tracking |
| `docs pre-commit` | Generate UPDATE-SUMMARY and changelog before commit |

---

## Pre-Commit Workflow

Before every commit, this skill should:

1. **Detect Changes:** Analyze staged files and recent modifications
2. **Update UPDATE-SUMMARY.md:** Summarize what changed
3. **Update/Create Changelog:** If version changed, create new changelog entry
4. **Review Milestone:** If working on milestone, update progress

---

## Writing Style Guide

### General Rules

1. **Be Concise:** Short sentences, bullet points
2. **Be Specific:** Include file paths, versions, concrete examples
3. **Use Status Icons:**
   - ✅ Completed/Done
   - ⏳ In Progress
   - ❌ Not Started/Planned
   - 🔨 Under Construction
4. **Include Version Info:** Note which version doc was last updated
5. **Date Format:** Full date (e.g., "February 25, 2026")

### Formatting

- **Headers:** `#` for title, `##` for sections, `###` for subsections
- **Code Blocks:** Always specify language (```typescript, ```bash)
- **Tables:** Use for structured data (versions, APIs, configs)
- **ASCII Diagrams:** Use for architecture visualizations

### Code Examples

Always include:
- File path as comment
- Brief description
- Complete, runnable examples

```typescript
// src/utils/example.ts
// Description of what this does

export function example() {
  // implementation
}
```

---

## Audit Checklist

When auditing documentation, verify:

- [ ] `/docs` directory exists at project root
- [ ] All numbered topics (01-09) exist
- [ ] BRAND-GUIDELINES.md exists (if branding defined)
- [ ] UPDATE-SUMMARY.md exists and is current
- [ ] `/docs/changelogs/` exists with version files
- [ ] `/docs/milestone/` exists for active development
- [ ] All docs follow writing style guide
- [ ] Version numbers are consistent across docs
- [ ] No orphaned or outdated documentation
- [ ] Code examples are accurate and runnable
- [ ] Architecture diagrams are current

---

## Usage Examples

```
User: "Create docs for this project"
→ Investigate codebase → Initialize full /docs structure with templates

User: "Check if my docs are complete"
→ Audit against required structure → Report missing/outdated files

User: "Create changelog for v1.2.0"
→ Analyze git diff → Generate version-1.2.0.md

User: "I'm about to commit these changes"
→ Update UPDATE-SUMMARY.md → Create changelog entry if needed

User: "Create milestone for auth feature"
→ Create /docs/milestone/auth-feature/ with plan.md
```

---

## Reference Files

For detailed templates and examples, see:
- `references/templates.md` - All documentation templates
- `references/changelog-format.md` - Changelog writing guide
- `references/milestone-format.md` - Milestone tracking guide