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

description

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:

# 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:

# 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.