Documentation Best Practices

This skill provides guidance for creating consistent, professional documentation for the MTG Agent project implementation.

Purpose

Maintain high-quality, actionable documentation that follows senior developer standards with:

• Clear task breakdowns with time estimates
• Comprehensive verification steps
• Rollback procedures for safety
• Testing integrated throughout
• Professional commit messages

When to Use This Skill

Use this skill when:

• Creating new phase documentation
• Writing task breakdowns for implementation
• Documenting verification procedures
• Setting up testing requirements
• Creating progress tracking documents
• Writing commit messages
• Updating implementation plans

Documentation Structure Standards

Phase README Format

Each phase README should include:

1. Phase Overview

   • Phase number and name
   • Status (Not Started, In Progress, Completed)
   • Duration estimate
   • Prerequisites

2. Objectives

   • Clear, measurable goals
   • 3-5 bullet points max
   • Specific deliverables

3. Why This Phase

   • Business/technical justification
   • Dependencies explained
   • Risk mitigation

4. Sub-Phases

   • List of sub-phases with brief descriptions
   • Estimated time for each
   • Dependencies between sub-phases

5. Success Criteria

   • Checklist of completion requirements
   • Verification that phase is truly done
   • Performance targets if applicable

6. Next Phase

   • Link to next phase
   • What will be built upon

Task Documentation Format

Each task should include:

1. Task Header

   ### Task X.Y: [Clear Task Name]
   **Estimated Time:** X minutes/hours
   **Prerequisites:** [What must be done first]
   

2. Objectives

   • What this task accomplishes
   • Why it's necessary

3. Steps

   • Numbered, specific steps
   • Include commands to run
   • Code examples where applicable
   • File paths clearly stated

4. Verification

   **Verification:**
   ```bash
   # Commands to verify task completion
   command1
   command2
   

   Expected Output:

   • What success looks like

5. Success Criteria

   - [ ] Specific criterion 1
   - [ ] Specific criterion 2
   - [ ] Specific criterion 3
   

6. Common Issues

   • Known problems and solutions
   • Troubleshooting steps

Code Examples

To include code examples:

For Configuration Files:

**Create:** `path/to/file.ext`

```language
// Full file content here
// With comments explaining key parts
```

For Commands:

```bash
# Comment explaining what this does
command --flag value
```

For Multi-Step Procedures:

```bash
# Step 1: Setup
command1

# Step 2: Execute
command2

# Step 3: Verify
command3
```

Verification Steps Format

Every task must include verification:

**Verification:**
```bash
# Test command 1
curl http://localhost:3000/health

# Test command 2
npm test

# Test command 3
docker-compose ps

Expected Output:

• Service returns 200 OK
• All tests pass
• All containers running

Success Criteria:

• Command 1 passes
• Command 2 passes
• Command 3 passes

### Rollback Procedures

Include rollback steps for safety:

```markdown
## Rollback Procedure

If this task causes issues:

```bash
# Step 1: Stop services
docker-compose down

# Step 2: Restore from backup
git checkout <previous-commit>

# Step 3: Restart
docker-compose up -d

When to Rollback:

• Verification fails repeatedly
• Breaks existing functionality
• Introduces security vulnerability

## Commit Message Standards

Follow conventional commits:

():