krzysztofsurdy/report-writer

Report Generator

Generate a professional, standalone HTML report summarizing the work you just completed -- bug fixes, features, refactoring, investigations, or debug sessions. The report opens automatically in the default browser.

When to Use

• After completing work on a ticket (use with the ticket-delivery skill)
• After a debug/investigation session
• To document architectural decisions
• To summarize a refactoring effort
• Whenever you want a polished record of what was done and why

Quick Start

/report-writer PROJ-1234
/report-writer auth-migration-investigation
/report-writer                  # auto-names from branch

Report Types

Bug Fix Report

Sections to include:

1. Problem Statement -- What was broken, who was affected, symptoms
2. Root Cause Analysis -- Why it happened, the chain of events
3. Investigation Timeline -- Steps taken to diagnose
4. Solution -- What was changed and why this approach
5. Files Changed -- List of modified files with brief descriptions
6. Testing -- How the fix was verified
7. Impact Assessment -- Risk level, rollback plan, monitoring

Feature Report

Sections to include:

1. Overview -- What the feature does, business context
2. Architecture -- How it fits into the system, design decisions
3. Implementation Details -- Key components, patterns used
4. Files Changed -- New and modified files
5. Configuration -- Any new config, env vars, feature flags
6. Testing -- Test coverage, edge cases considered
7. Deployment Notes -- Migration steps, dependencies, rollout plan

Refactoring Report

Sections to include:

1. Motivation -- Why the refactoring was needed
2. Scope -- What was refactored, what was left untouched
3. Approach -- Strategy used (e.g., strangler fig, parallel implementation)
4. Before/After -- Key structural comparisons
5. Files Changed -- Renamed, moved, deleted, created
6. Risk Assessment -- What could break, how it was mitigated
7. Follow-Up -- Remaining tech debt, future improvements

Investigation / Debug Report

Sections to include:

1. Objective -- What was being investigated
2. Hypothesis -- Initial theories
3. Investigation Timeline -- Chronological steps and findings
4. Evidence -- Logs, metrics, code snippets
5. Conclusions -- What was found
6. Recommendations -- Suggested actions
7. Open Questions -- Unresolved items

Generating the Report

Step 1: Gather Data

Collect information from your working session:

# Detect the main branch dynamically
MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# Get the merge base
MERGE_BASE=$(git merge-base HEAD "$MAIN_BRANCH")

# Changed files
git diff --name-status "$MERGE_BASE"..HEAD

# Full diff
git diff "$MERGE_BASE"..HEAD

# Commit log
git log --oneline "$MERGE_BASE"..HEAD

# Stats
git diff --stat "$MERGE_BASE"..HEAD

Step 2: Build the HTML

Use the template at references/template.html as the base. Replace the placeholder tokens:

| Token | Replace With | |-------|-------------| | {{REPORT_TITLE}} | Report title (e.g., "PROJ-1234: Fix payment timeout") | | {{REPORT_SUBTITLE}} | Short subtitle or ticket summary | | {{REPORT_DATE}} | Date in format "January 15, 2025" | | {{REPORT_CONTENT}} | All HTML content sections (see components below) | | {{TICKET_ID}} | Ticket identifier (e.g., "PROJ-1234") | | {{BRANCH_NAME}} | Git branch name | | {{AUTHOR_NAME}} | Author name | | {{GENERATED_BY}} | "report-writer" |

Step 3: Save and Open

# Save to /tmp
REPORT_PATH="/tmp/report-$(date +%Y%m%d-%H%M%S).html"

# Write the HTML content to the file
cat > "$REPORT_PATH" << 'REPORT_EOF'
... generated HTML ...
REPORT_EOF

# Open in the default browser
# macOS:    open "$REPORT_PATH"
# Linux:    xdg-open "$REPORT_PATH"
# Windows:  start "$REPORT_PATH"

HTML Components Reference

All components go inside the {{REPORT_CONTENT}} placeholder.

Section with Icon

Uses Bootstrap Icons via CDN (already included in the template).

<div class="section mb-9">
    <h2 class="text-xl font-bold text-slate-900 mb-4 pb-2 border-b border-slate-200 flex items-center gap-2">
        <i class="bi bi-search"></i> Root Cause Analysis
    </h2>
    <p>Description text here...</p>
</div>

Section Icon Reference

| Icon class | Use For | |------|---------| | bi bi-bullseye | Overview, Objective, Problem Statement | | bi bi-search | Root Cause, Investigation, Analysis | | bi bi-tools | Solution, Implementation, Approach | | bi bi-folder2-open | Files Changed, Scope | | bi bi-check-circle | Testing, Verification | | bi bi-bar-chart | Impact, Metrics, Statistics | | bi bi-rocket-takeoff | Deployment, Next Steps | | bi bi-clock-history | Timeline, Chronology | | bi bi-lightbulb | Recommendations, Insights | | bi bi-exclamation-triangle | Risks, Warnings, Caveats | | bi bi-building | Architecture, Design | | bi bi-card-checklist | Summary, Configuration | | bi bi-gear | Configuration, Setup | | bi bi-pencil-square | Notes, Documentation |

Info Card

<div class="card">
    <strong>Key Finding:</strong> The timeout was caused by a missing index
    on the <code>payments</code> table, leading to full table scans under load.
</div>

Highlighted Card (Warning/Important)

<div class="card highlight">
    <strong>⚠️ Important:</strong> This change requires a database migration
    to be run before deployment.
</div>

Timeline

<div class="timeline">
    <div class="timeline-item">
        <div class="timeline-marker"></div>
        <div class="timeline-content">
            <strong>Step 1: Reproduced the issue</strong>
            <p>Confirmed the timeout occurs on orders with 50+ line items...</p>
        </div>
    </div>
    <div class="timeline-item">
        <div class="timeline-marker"></div>
        <div class="timeline-content">
            <strong>Step 2: Identified slow query</strong>
            <p>Used <code>EXPLAIN ANALYZE</code> to find the missing index...</p>
        </div>
    </div>
</div>

Code Block

<pre><code># Before: N+1 query pattern
for order in orders:
    items = order_repo.find_by_order_id(order.id)

# After: Eager loading with single query
orders = order_repo.find_with_items(criteria)</code></pre>

Impact Grid

<div class="impact-grid">
    <div class="impact-item low">
        <strong>Performance</strong>
        <span>Query time: 2.3s → 45ms</span>
    </div>
    <div class="impact-item medium">
        <strong>Risk Level</strong>
        <span>Medium -- new index on production table</span>
    </div>
    <div class="impact-item high">
        <strong>Urgency</strong>
        <span>High -- affecting 12% of checkouts</span>
    </div>
</div>

Impact item classes: low (green), medium (amber), high (red).

Decision Log

<div class="decision-log">
    <div class="decision">
        <div class="decision-title">Accepted: Use composite index instead of separate indexes</div>
        <div class="decision-detail">
            <strong>Rationale:</strong> Composite index covers both the WHERE clause
            and ORDER BY, avoiding a filesort. Benchmarked 3x faster than two
            separate indexes.
        </div>
    </div>
    <div class="decision">
        <div class="decision-title">Rejected: Caching layer</div>
        <div class="decision-detail">
            <strong>Reason:</strong> Would add complexity and staleness risk.
            The index fix resolves the root cause without adding infrastructure.
        </div>
    </div>
</div>

File List

<div class="file-list">
    <div class="file-item">
        <span class="file-name">src/repository/order_repository.ext</span>
        <span class="file-badge modified">Modified</span>
        <div class="file-detail">Added eager loading for order items</div>
    </div>
    <div class="file-item">
        <span class="file-name">migrations/20250115_add_order_index.ext</span>
        <span class="file-badge added">Added</span>
        <div class="file-detail">Composite index on (user_id, created_at)</div>
    </div>
    <div class="file-item">
        <span class="file-name">src/service/legacy_order_loader.ext</span>
        <span class="file-badge deleted">Deleted</span>
        <div class="file-detail">Replaced by repository method</div>
    </div>
</div>

File badge classes: added (green), modified (blue), deleted (red).

Stats Bar

<div class="stats-bar">
    <div class="stat">
        <div class="stat-value">7</div>
        <div class="stat-label">Files Changed</div>
    </div>
    <div class="stat">
        <div class="stat-value">+142</div>
        <div class="stat-label">Lines Added</div>
    </div>
    <div class="stat">
        <div class="stat-value">-89</div>
        <div class="stat-label">Lines Removed</div>
    </div>
    <div class="stat">
        <div class="stat-value">5</div>
        <div class="stat-label">Tests Added</div>
    </div>
</div>

Advanced Components

Horizontal Timeline (Phase Overview)

<div class="horizontal-timeline">
    <div class="ht-phase completed">
        <div class="ht-marker">1</div>
        <div class="ht-label">Discovery</div>
    </div>
    <div class="ht-connector completed"></div>
    <div class="ht-phase completed">
        <div class="ht-marker">2</div>
        <div class="ht-label">Analysis</div>
    </div>
    <div class="ht-connector active"></div>
    <div class="ht-phase active">
        <div class="ht-marker">3</div>
        <div class="ht-label">Implementation</div>
    </div>
    <div class="ht-connector"></div>
    <div class="ht-phase">
        <div class="ht-marker">4</div>
        <div class="ht-label">Verification</div>
    </div>
</div>

Phase classes: (none) = pending, active = current, completed = done.

Phased Vertical Timeline

<div class="phase-timeline">
    <div class="phase-group">
        <div class="phase-header">Phase 1: Discovery</div>
        <div class="timeline">
            <div class="timeline-item">
                <div class="timeline-marker"></div>
                <div class="timeline-content">
                    <strong>Identified failing tests</strong>
                    <p>3 integration tests failing intermittently on CI...</p>
                </div>
            </div>
        </div>
    </div>
    <div class="phase-group">
        <div class="phase-header">Phase 2: Root Cause</div>
        <div class="timeline">
            <div class="timeline-item">
                <div class="timeline-marker"></div>
                <div class="timeline-content">
                    <strong>Race condition in event handler</strong>
                    <p>Two listeners processing the same event concurrently...</p>
                </div>
            </div>
        </div>
    </div>
</div>

Data Table

<table class="data-table">
    <thead>
        <tr>
            <th>Endpoint</th>
            <th>Before</th>
            <th>After</th>
            <th>Improvement</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>/api/orders</code></td>
            <td>2,340ms</td>
            <td>45ms</td>
            <td class="positive">98% faster</td>
        </tr>
        <tr>
            <td><code>/api/users</code></td>
            <td>180ms</td>
            <td>165ms</td>
            <td class="neutral">8% faster</td>
        </tr>
    </tbody>
</table>

Table cell classes: positive (green), negative (red), neutral (gray).

Arrow Annotation

<div class="arrow-annotation">
    <div class="arrow-from">
        <code>OrderService.checkout()</code>
    </div>
    <div class="arrow-line">→</div>
    <div class="arrow-to">
        <code>PaymentGateway.charge()</code>
    </div>
    <div class="arrow-label">Timeout occurs here (>30s)</div>
</div>

Design Principles

1. Standalone -- The HTML file must work with zero external dependencies. All CSS and JS are inlined.
2. Professional -- Clean typography, consistent spacing, subtle color palette. No garish colors.
3. Informative -- Every section should add value. Don't pad with boilerplate.
4. Scannable -- Use headers, cards, and visual hierarchy so readers can skim.
5. Printable -- The report should look good when printed (the template includes print styles).
6. Accurate -- All file names, line counts, and code snippets must match the actual work done.

Integration with ticket-delivery

When using report-writer after completing a ticket with ticket-delivery:

# 1. Complete the ticket work
/ticket-delivery PROJ-1234

# 2. Generate a report summarizing what was done
/report-writer PROJ-1234

The report generator will automatically gather git diff data, commit history, and file changes from your working branch.

Reference Files

| Reference | Contents | |---|---| | template.html | Full standalone HTML template with all CSS, JS, and component styles baked in |

Integration with Other Skills

| Situation | Recommended Skill | |---|---| | When completing a ticket end-to-end | ticket-delivery | | When writing a PR description | pr-message-writer |

Examples

/report-writer PROJ-1234          # Bug fix report for ticket PROJ-1234
/report-writer PROJ-5678          # Feature report for ticket PROJ-5678
/report-writer PROJ-9012          # Refactoring report for ticket PROJ-9012
/report-writer auth-investigation  # Investigation report (no ticket)
/report-writer                     # Auto-detect from branch name