gh-rasmusgodske-dev-agent-workflow-project-roles/commands/docs/process-documentation-reports.md

---
description: Process pending documentation gap reports and generate missing documentation
---

# Process Documentation Reports

You are processing documentation gap reports generated by the research agent to create or improve project documentation.

## Your Mission

Review pending research reports, verify their findings, decide what documentation changes are needed, and implement those changes following project conventions.

## Your Role in the Workflow

This command is part of the **research-driven documentation system**. Here's how it fits:

1. **Research agent** (subagent) explores codebase when Claude needs context
2. **Gap reports** are created and stored in `docs/_research/lacking/pending/`
3. **You (this command)** process reports and generate documentation
4. **Documentation writer skill** ensures quality and consistency

**Report lifecycle you manage:**
```
pending/          # New reports (you start here)
    ↓
in-progress/      # Currently processing (you create plan.md)
    ↓
processed/        # Complete (you create resolution.md)
```

**Your responsibilities:**
- Review what research agent found
- Decide what documentation to create/update
- Generate high-quality documentation following conventions
- Update INDEX.md for discoverability
- Track what was done in resolution reports

## Process Overview

1. Find pending reports
2. Process each report one at a time
3. For each report:
   - Read and verify the research findings
   - Create a documentation plan
   - Get user approval
   - Generate the documentation
   - Mark report as processed

## Step-by-Step Instructions

### Step 1: Find Pending Reports

Use Glob to find all pending reports:
```
Glob: docs/_research/lacking/pending/*/report.md
```

If no reports found:
- Tell the user: "No pending documentation reports found. All caught up!"
- Stop here

If reports found:
- Tell the user: "Found {N} pending documentation reports."
- List them briefly: "{timestamp}_{slug} - {topic}"
- Ask: "Process these reports? [yes/no]"

If user says no, stop.

### Step 2: Process Each Report Sequentially

For EACH report (one at a time, don't batch):

#### 2a. Read the Report

```
Read: docs/_research/lacking/pending/{timestamp}_{slug}/report.md
```

Parse the report to understand:
- What topic was researched
- What documentation exists
- What gaps were found
- Code locations referenced

#### 2b. Verify Findings (Quick Spot Check)

Don't redo the entire research, but quickly verify:
- Check 1-2 docs the report says are missing (confirm they're actually missing)
- Read 1-2 docs the report says exist (confirm they match description)

If findings seem wrong:
- Tell the user
- Ask if they want to skip this report

#### 2c. Load Documentation Conventions

```
Use Glob to find: .claude/rules/documentation/**/*.md
Read all files found
```

Key files to load:
- `structure.md` - Documentation organization
- `file-mapping.md` - Where to place documentation
- `templates.md` - What structure to use
- `writing-style.md` - How to write quality content
- `index-maintenance.md` - How to update INDEX.md

These tell you:
- Documentation structure and format
- File naming conventions
- Where to place new documentation
- Templates to follow
- Style guidelines
- INDEX.md update rules

#### 2d. Create Documentation Plan

Based on the report and conventions, decide:
- What new documentation files to create
- What existing files to update
- Where to place them (following conventions)
- What to include in each

Create a plan.md file:

```
Write: docs/_research/lacking/{same-directory}/plan.md
```

Format:
```markdown
# Documentation Plan: {Topic}

Generated: {current timestamp}

## Proposed Changes

### 1. Create docs/domains/{domain}/features/{feature}.md
**Why:** {Reason based on research report}
**Content:**
- Section 1: {What will be documented}
- Section 2: {What will be documented}

### 2. Update docs/domains/{domain}/README.md
**Why:** {Reason}
**Changes:**
- Add feature to feature list
- Link to new documentation

### 3. Update docs/INDEX.md
**Why:** Ensure discoverability
**Changes:**
- Add entry: [{Topic}](path/to/doc.md) - {brief description}

## Estimated Impact
- {N} files created
- {N} files modified
- ~{N} lines of documentation added

## Code References Used
- `{path}:{line}` - {description}
- `{path}:{line}` - {description}
```

#### 2e. Show Plan to User

Present the plan clearly:
```
Report: {topic}
Priority: {priority}

I plan to:
- Create {N} new documentation file(s)
- Update {N} existing file(s)
- Add {N} INDEX.md entries

Details in: docs/_research/lacking/{directory}/plan.md

Proceed with this plan? [yes/no/skip]
```

If user says:
- **no**: Skip to next report (don't move to processed)
- **skip**: Move to next report (don't move to processed)
- **yes**: Continue to next step

#### 2f. Move to In-Progress

```
Bash: mv docs/_research/lacking/pending/{directory} docs/_research/lacking/in-progress/
```

This prevents processing the same report twice if something goes wrong.

#### 2g. Generate Documentation

Follow the plan you created:

**For each new file to create:**
1. Use the templates from `.claude/rules/documentation/templates.md`
2. Fill in content based on the research report
3. Include code references from the report (format from `writing-style.md`)
4. Follow the documentation format conventions
5. Write the file

**For each file to update:**
1. Read the existing file
2. Edit to add new content
3. Maintain existing style and format
4. Preserve existing content

**Always update INDEX.md:**
- Read current INDEX.md
- Add new entries in appropriate sections
- Maintain alphabetical order within sections
- Update the "Last updated" timestamp

#### 2h. Create Resolution Report

```
Write: docs/_research/lacking/in-progress/{directory}/resolution.md
```

Format:
```markdown
# Resolution: {Topic}

Processed: {timestamp}

## Actions Taken

- ✅ Created `{path}` ({N} lines)
- ✅ Updated `{path}` (added {description})
- ✅ Updated `docs/INDEX.md` (added {N} entries)

## Files Created
- {path}

## Files Modified
- {path}
- {path}

## Documentation Generated

Brief summary of what was documented and where to find it.

## Processed By
Claude Code documentation agent

## Notes
{Any relevant notes, issues encountered, or future improvements needed}
```

#### 2i. Move to Processed

```
Bash: mv docs/_research/lacking/in-progress/{directory} docs/_research/lacking/processed/
```

#### 2j. Report Completion

Tell the user:
```
✅ Processed: {topic}
   Created: {N} files
   Updated: {N} files

{N} reports remaining.
```

Then continue to the next report.

### Step 3: Final Summary

After processing all reports (or when user stops):

```
Documentation Processing Complete

Processed: {N} reports
Created: {N} new documentation files
Updated: {N} existing files

All pending reports have been addressed.
```

## Documentation Quality Guidelines

All quality guidelines, templates, and style rules are defined in `.claude/rules/documentation/README.md`.

When generating documentation:

1. **Follow conventions strictly** - All rules are in `.claude/rules/documentation/README.md`
2. **Use the templates** - Domain, feature, and layer templates are defined in conventions
3. **Cover research findings** - Address all aspects mentioned in the research report
4. **Update INDEX.md** - Critical for discoverability
5. **Update parent READMEs** - When adding features to domains or components to layers

The conventions file is the **single source of truth** for documentation standards.

## Special Cases

### Research Report is Unclear
If the report doesn't provide enough information:
- Note this in the plan
- Do additional research (read code files mentioned)
- Ask user if you should skip or proceed with limited info

### Documentation Already Exists
If you discover docs exist that the research agent missed:
- Note this in the plan
- Propose updates rather than new files
- Mark the report as processed with resolution noting this

### No Changes Needed
If after review, the existing documentation is actually sufficient:
- Create plan.md noting no changes needed
- Create resolution.md explaining why
- Move to processed
- Tell the user

### Code Has Changed
If code references in the report are outdated:
- Note this in plan
- Re-read current code
- Document current state
- Note in resolution that code has changed

## Error Handling

If errors occur during processing:
- Leave report in in-progress/
- Tell the user what went wrong
- Don't move to processed/
- User can manually fix and retry

## Best Practices

### One Report at a Time
- Process sequentially, not in parallel
- Get user approval for each
- Complete fully before moving to next

### Verify Before Writing
- Quickly check research findings
- Read conventions
- Plan before executing

### Be Consistent
- Follow project conventions strictly
- Match existing documentation style
- Use same terminology as existing docs

### Update the Index
- INDEX.md is critical for discoverability
- Always update it when creating new docs
- Keep it organized and current

## Example Session

```
User: /docs/process-reports

Claude: Found 2 pending documentation reports:
1. 2025-11-20_143022_auth-jwt-validation - Authentication JWT Validation
2. 2025-11-20_150135_payment-flow - Payment Processing Flow

Process these reports? [yes/no]

User: yes

Claude:
Report 1: Authentication JWT Validation (priority: high)

After reviewing the research findings, I plan to:
- Create docs/domains/authentication/features/jwt-validation.md
- Update docs/domains/authentication/README.md
- Create docs/layers/backend/services/auth-service.md
- Update docs/INDEX.md (3 new entries)

Details in: docs/_research/lacking/pending/2025-11-20_143022_auth-jwt-validation/plan.md

Proceed with this plan? [yes/no/skip]

User: yes

Claude:
[Creates documentation files...]

✅ Processed: Authentication JWT Validation
   Created: 2 files (jwt-validation.md, auth-service.md)
   Updated: 2 files (authentication/README.md, INDEX.md)

1 report remaining.

Report 2: Payment Processing Flow (priority: medium)
...
```

## Important Reminders

- **Load conventions first**: Always read `.claude/rules/documentation/README.md`
- **Verify findings**: Spot-check the research report
- **Plan before acting**: Create plan.md and get approval
- **Follow templates**: Use the templates from conventions
- **Update INDEX.md**: Critical for discoverability
- **Create resolution**: Document what you did
- **Move to processed**: So it's not processed again
- **Process sequentially**: One report at a time, with user approval

Your goal is to systematically eliminate documentation gaps while maintaining high quality and consistency across all documentation.