---
name: report-writing
description: Generate structured task completion reports in two synchronized formats - a concise chat summary and a detailed documentation file. Use this skill when completing tasks that require formal documentation, audit trails, or reproducible records of work performed. Particularly useful for specification-driven development, API implementation, or any workflow requiring both user-facing summaries and comprehensive technical documentation.
---

# Report Writing Skill

This skill provides a standardized protocol for generating task completion reports that serve dual purposes: immediate user communication and long-term documentation.

## When to Use This Skill

Invoke this skill upon successful completion of any tasks

## Core Workflow

### Two Synchronized Outputs

Generate both outputs synchronously upon task completion:

#### 1. Chat Interface Report

Deliver a concise, user-friendly summary directly to the chat interface:

- **Format**: Brief, accessible language
- **Content**: Task status, key outcomes, next steps (if applicable)
- **Timing**: Immediate upon completion
- **Audience**: End user or stakeholder

#### 2. Detailed Documentation File

Create a comprehensive Markdown file with full implementation details:

- **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`.