Report Writing Skill

• Location: reports/{specifications_document_name}/task_{task_number}_completed.md
• Naming Example: reports/ast-transcription-api/task_10_1_completed.md
• Structure: See template in references/report-template.md

Required Sections in Documentation File

Structure the detailed documentation file with these sections in order:

1. Chat Interface Output

   • Reproduce the complete chat summary verbatim at the top
   • Ensures consistency between both deliverables
   • Provides context for readers reviewing only the file

2. Task Overview

   • Brief description of the task
   • Stated objectives and success criteria
   • Reference to parent specification or project context

3. Execution Timeline

   • Chronological sequence of actions taken
   • Timestamp each major step
   • Include decision points and reasoning

4. Inputs/Outputs

   • All data processed (files read, APIs called, databases queried)
   • All artifacts generated (files created, API responses, database modifications)
   • Configuration changes or environment setup

5. Error Handling

   • Any warnings encountered during execution
   • Errors that occurred and how they were resolved
   • Validation failures and remediation steps
   • Edge cases discovered

6. Final Status

   • Success confirmation with criteria met
   • Summary of all deliverables produced
   • Known limitations or follow-up items
   • Links to related documentation or resources

Quality Assurance Checklist

Before finalizing reports, verify:

• Consistency: Chat summary and file documentation align perfectly
• Accuracy: All timestamps are correct and chronologically ordered
• Completeness: All required sections are present with substantive content
• Reproducibility: Sufficient detail exists to recreate the task execution
• Clarity: Technical terms are defined, acronyms explained on first use
• Traceability: Links to specifications, commits, or related tasks are included

Implementation Guidelines

File Organization

Create the reports/ directory structure as needed:

reports/
├── {specification-name-1}/
│   ├── task_1_completed.md
│   ├── task_2_completed.md
│   └── task_3_completed.md
└── {specification-name-2}/
    └── task_1_completed.md

Naming Conventions

Follow these patterns strictly:

• Directory: Lowercase, hyphen-separated (e.g., ast-transcription-api)
• File: task_{number}_completed.md or task_{number}_{subnumber}_completed.md
• Examples: task_1_completed.md, task_10_1_completed.md

Writing Style

• Use active voice in timeline descriptions
• Be specific about tools, commands, and file paths
• Include exact error messages in error handling section
• Use code blocks for commands, file contents, or outputs
• Add headings to improve scanability

Example Usage Scenarios

Scenario 1: API Implementation

After implementing a REST API endpoint:

1. Chat: "Successfully implemented the /api/users endpoint with GET and POST methods. Returns user list with pagination, creates new users with validation. All tests passing."

2. File: reports/user-management-api/task_3_completed.md containing:

   • The above chat output
   • Task overview (implement user CRUD endpoints)
   • Timeline (created route files, added validation, wrote tests, deployed)
   • Inputs/outputs (schema files, test data, API responses)
   • Error handling (validation edge cases, database connection retry logic)
   • Final status (endpoints live, 100% test coverage, documentation updated)

Scenario 2: Database Migration

After completing a database schema update:

1. Chat: "Database migration completed successfully. Added 'preferences' table with foreign key to users. Backfilled data for 1,247 existing users. No downtime required."

2. File: reports/user-preferences-feature/task_2_1_completed.md containing:

   • The above chat output
   • Full migration details, SQL scripts used, rollback plan tested
   • Verification queries run and their results
   • Performance impact analysis

References

For detailed template structure with placeholders, see references/report-template.md.