/writing-dev-reports

name: ring:writing-dev-reports
description: "Writing a structured markdown dev report for a completed development epic: reads accumulated epic metrics (TDD, coverage, delivery, lint, file-size, license), computes a quality score with tiers, and records root-cause and next-cycle improvements. Use after an epic completes in ring:running-dev-cycle or when asked for a development feedback report. Skip for documentation-only epics or outside a dev cycle."

Dev Report — Feedback Loop

When to use

• After epic completion in any dev cycle
• User requests a development report or feedback summary
• ring:running-dev-cycle Gate 10 handoff

Skip when

• Epic was documentation-only with no code changes
• Not inside a development cycle

Collects metrics and writes a structured report for completed development epics.

Step 1: Collect Metrics

Read `accumulated_metrics` from each completed epic (`state.epics[].accumulated_metrics`), then gather the following per epic:

epic_id: {unit_id}
completed_at: {ISO timestamp}
agent_used: {ring:backend-go | ring:frontend | etc.}
language: {go | typescript | python}
service_type: {api | worker | batch | cli | frontend | bff}

tdd:
  red_status: completed | skipped | failed
  green_status: completed | skipped | failed

coverage:
  actual_percent: {float}
  threshold: {float}
  verdict: PASS | FAIL

delivery:
  requirements_total: {int}
  requirements_delivered: {int}
  verdict: PASS | PARTIAL | FAIL

quality:
  lint_pass: true | false
  file_size_violations: {int}
  license_violations: {int}
  migration_safety: PASS | FAIL | N/A

Step 2: Calculate Score

score = 0

TDD RED completed:    +20
TDD GREEN completed:  +20
Coverage ≥ threshold: +20
Delivery PASS:        +20
Lint pass:            +10
No file size violations: +5
License headers OK:   +5

Total: 100 possible

Score tiers:

• 90-100: Excellent
• 80-89: Good
• 70-79: Acceptable
• < 70: Needs attention → root cause required

Step 3: Write Report

Save to `docs/ring:writing-dev-reports/{epic_id}-{timestamp}.md`:

# Dev Report: {epic_id}

**Completed:** {timestamp}
**Agent:** {agent_used}
**Language:** {language} | **Service Type:** {service_type}

## Score: {score}/100 ({tier})

## Metrics

| Metric | Value | Status |
|--------|-------|--------|
| TDD RED | {status} | ✅/❌ |
| TDD GREEN | {status} | ✅/❌ |
| Coverage | {actual}% (threshold: {threshold}%) | ✅/❌ |
| Delivery | {delivered}/{total} requirements | ✅/⚠️/❌ |
| Lint | {pass/fail} | ✅/❌ |
| File Size | {violations} violations | ✅/❌ |
| License | {violations} violations | ✅/❌ |

## Delivery Traceability

| Requirement | Status | Evidence |
|-------------|--------|----------|
{per-requirement rows}

## Issues Found

{list of ISSUE-XXX with severity and description}

## Root Cause (if score < 70)

{mandatory analysis: what caused the gaps, pattern identification}

## Improvements for Next Cycle

{1-3 concrete, actionable improvements}

Severity Reference

| Severity | Criteria | |----------|----------| | CRITICAL | Score 0 (rejected), complete workflow failure | | HIGH | Score < 70, threshold breach | | MEDIUM | Score 70-79, recurring pattern emerging | | LOW | Score 80-89, minor improvements available |