init
This commit is contained in:
133
.opencode/skills/retro/references/metrics-guide.md
Normal file
133
.opencode/skills/retro/references/metrics-guide.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Metrics Reference Guide
|
||||
|
||||
Each metric: what it measures, why it matters, interpretation guidance, and the git command to compute it.
|
||||
|
||||
---
|
||||
|
||||
## Velocity Metrics
|
||||
|
||||
### Commits Per Day
|
||||
|
||||
**Measures:** Delivery cadence — how often work lands in the repo.
|
||||
**Why it matters:** Low frequency may indicate large batched PRs (risky merges); high frequency with tiny commits suggests good trunk-based dev hygiene.
|
||||
**Interpretation:**
|
||||
- `< 1/day` — infrequent; check for blocked PRs or slow review cycles
|
||||
- `1-3/day` — healthy for a solo dev or small team
|
||||
- `> 5/day` — high activity; verify commits are meaningful, not noise
|
||||
|
||||
```bash
|
||||
git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
|
||||
| cut -d' ' -f1 | sort | uniq -c
|
||||
```
|
||||
|
||||
### Active Day Ratio
|
||||
|
||||
**Measures:** What fraction of working days had at least one commit.
|
||||
**Why it matters:** Consistent daily progress vs burst-then-idle patterns.
|
||||
**Interpretation:** `> 70%` = consistent; `< 40%` = batchy; investigate blockers.
|
||||
|
||||
```bash
|
||||
# Days with activity
|
||||
git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
|
||||
| cut -d' ' -f1 | sort -u | wc -l
|
||||
# Divide by total calendar days in period
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Health Metrics
|
||||
|
||||
### LOC Added / Removed / Net
|
||||
|
||||
**Measures:** Raw volume of code written and deleted.
|
||||
**Why it matters:** Net negative LOC (more deleted than added) is often a sign of healthy refactoring. Very high churn on specific files is a risk signal.
|
||||
**Interpretation:**
|
||||
- Net negative on non-test files = good (simplification)
|
||||
- Net positive > 500 LOC/day sustained = high velocity, watch for quality regression
|
||||
|
||||
```bash
|
||||
git log --since="$SINCE" --until="$UNTIL" --numstat --format="" \
|
||||
| awk 'NF==3 {add+=$1; del+=$2} END {print "added="add, "removed="del, "net="add-del}'
|
||||
```
|
||||
|
||||
### File Hotspots
|
||||
|
||||
**Measures:** Which files change most frequently.
|
||||
**Why it matters:** High-churn files are coupling magnets and defect attractors. Files appearing in > 30% of commits warrant refactoring.
|
||||
**Interpretation:** Top 3 hotspots in every sprint signal architectural debt.
|
||||
|
||||
```bash
|
||||
git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
|
||||
| sort | uniq -c | sort -rn | head -10
|
||||
```
|
||||
|
||||
### Churn Rate
|
||||
|
||||
**Measures:** `(LOC_added + LOC_removed) / max(LOC_net, 1)` — how much code was rewritten vs kept.
|
||||
**Why it matters:** Churn > 3x net LOC = significant rework; investigate root cause (unclear requirements, unstable APIs, poor initial design).
|
||||
**Interpretation:**
|
||||
- `1.0 - 1.5` = clean, additive work
|
||||
- `1.5 - 3.0` = moderate iteration (normal)
|
||||
- `> 3.0` = high rework; flag for retro discussion
|
||||
|
||||
---
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
### Test-to-Code Ratio
|
||||
|
||||
**Measures:** `test_file_changes / total_file_changes * 100`
|
||||
**Why it matters:** Proxy for whether tests accompany new code. Does not measure test quality, only presence.
|
||||
**Interpretation:**
|
||||
- `> 30%` = tests accompanying changes (healthy)
|
||||
- `10-30%` = some test coverage added
|
||||
- `< 10%` = tests lagging behind; technical debt accumulating
|
||||
|
||||
```bash
|
||||
# Test file changes
|
||||
git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
|
||||
| grep -E "(\.test\.|\.spec\.|__tests__|test_)" | wc -l
|
||||
|
||||
# Total file changes
|
||||
git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
|
||||
| grep -v "^$" | wc -l
|
||||
```
|
||||
|
||||
### Commit Type Distribution
|
||||
|
||||
**Measures:** Breakdown of conventional commit types (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `hotfix`).
|
||||
**Why it matters:** Ratio reveals focus. Heavy `fix` ratio may indicate quality issues; heavy `chore` may mean infra debt; balanced mix = sustainable pace.
|
||||
**Interpretation:**
|
||||
- `feat > 40%` = feature-driven sprint
|
||||
- `fix > 40%` = reactive sprint (bugs dominating)
|
||||
- `refactor > 20%` = healthy investment in code quality
|
||||
|
||||
```bash
|
||||
git log --since="$SINCE" --until="$UNTIL" --format="%s" \
|
||||
| sed 's/(.*//' | sed 's/:.*//' | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Plan Metrics
|
||||
|
||||
### Plan Completion Rate
|
||||
|
||||
**Measures:** Closed GitHub issues / total issues opened in period (or checkbox ratio in plan files).
|
||||
**Why it matters:** Tracks delivery predictability. Consistent undercompletion signals scope inflation or estimation issues.
|
||||
**Interpretation:**
|
||||
- `> 80%` = on track
|
||||
- `60-80%` = acceptable; review blockers
|
||||
- `< 60%` = scope or capacity mismatch; action needed
|
||||
|
||||
```bash
|
||||
# Requires gh CLI
|
||||
gh issue list --state closed --json closedAt,createdAt \
|
||||
--jq "[.[] | select(.closedAt >= \"$SINCE\")] | length"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Plan file checkbox scan (fallback)
|
||||
grep -r "\- \[x\]" plans/ | wc -l # completed
|
||||
grep -r "\- \[ \]" plans/ | wc -l # open
|
||||
```
|
||||
110
.opencode/skills/retro/references/report-template.md
Normal file
110
.opencode/skills/retro/references/report-template.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Retrospective Report — {TIMEFRAME}
|
||||
|
||||
**Period:** {SINCE} → {UNTIL}
|
||||
**Generated:** {TODAY}
|
||||
**Repo:** {REPO_NAME}
|
||||
**Authors:** {AUTHOR_COUNT} active
|
||||
|
||||
---
|
||||
|
||||
## Velocity
|
||||
|
||||
| Metric | Value | {COMPARE_COL} |
|
||||
|--------|-------|---------------|
|
||||
| Total commits | {TOTAL_COMMITS} | {DELTA_COMMITS} |
|
||||
| Commits / day | {COMMITS_PER_DAY} | {DELTA_COMMITS_DAY} |
|
||||
| Active days | {ACTIVE_DAYS} / {PERIOD_DAYS} ({ACTIVE_PCT}%) | {DELTA_ACTIVE} |
|
||||
| Files changed | {FILES_CHANGED} | {DELTA_FILES} |
|
||||
|
||||
*Remove delta column if `--compare` not set.*
|
||||
|
||||
---
|
||||
|
||||
## Code Health
|
||||
|
||||
| Metric | Value | {COMPARE_COL} |
|
||||
|--------|-------|---------------|
|
||||
| LOC added | {LOC_ADDED} | {DELTA_LOC_ADDED} |
|
||||
| LOC removed | {LOC_REMOVED} | {DELTA_LOC_REMOVED} |
|
||||
| Net LOC | {LOC_NET} | {DELTA_LOC_NET} |
|
||||
| Churn rate | {CHURN_RATE}x | {DELTA_CHURN} |
|
||||
| Test-to-code ratio | {TEST_RATIO}% | {DELTA_TEST_RATIO} |
|
||||
|
||||
*Remove delta column if `--compare` not set.*
|
||||
|
||||
---
|
||||
|
||||
## Commit Distribution
|
||||
|
||||
```
|
||||
{COMMIT_TYPE_BAR_OR_TABLE}
|
||||
```
|
||||
|
||||
Example format:
|
||||
```
|
||||
feat ████████████ 12 (40%)
|
||||
fix ████████ 8 (27%)
|
||||
chore ████ 4 (13%)
|
||||
refactor ███ 3 (10%)
|
||||
test ██ 2 (7%)
|
||||
docs █ 1 (3%)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Hotspots
|
||||
|
||||
Top files by change frequency:
|
||||
|
||||
| Rank | File | Changes |
|
||||
|------|------|---------|
|
||||
| 1 | {FILE_1} | {COUNT_1} |
|
||||
| 2 | {FILE_2} | {COUNT_2} |
|
||||
| 3 | {FILE_3} | {COUNT_3} |
|
||||
| ... | ... | ... |
|
||||
|
||||
---
|
||||
|
||||
## Plan Progress
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Completed tasks | {TASKS_DONE} |
|
||||
| Open tasks | {TASKS_OPEN} |
|
||||
| Completion rate | {PLAN_PCT}% |
|
||||
| Issues closed (period) | {ISSUES_CLOSED} |
|
||||
|
||||
---
|
||||
|
||||
## Team Breakdown
|
||||
|
||||
*Include only when `--team` flag is set. Otherwise omit this section.*
|
||||
|
||||
| Author | Commits | LOC Net | Types |
|
||||
|--------|---------|---------|-------|
|
||||
| {AUTHOR_1} | {COMMITS_1} | {LOC_1} | {TYPES_1} |
|
||||
| {AUTHOR_2} | {COMMITS_2} | {LOC_2} | {TYPES_2} |
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- [OK] {POSITIVE_FINDING_1}
|
||||
- [OK] {POSITIVE_FINDING_2}
|
||||
- [!] {NOTABLE_FINDING}
|
||||
|
||||
*Replace with 2-4 factual observations from the data. No invented praise.*
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. **{ACTION_1}** — {RATIONALE_1} (based on {METRIC})
|
||||
2. **{ACTION_2}** — {RATIONALE_2} (based on {METRIC})
|
||||
3. **{ACTION_3}** — {RATIONALE_3} (based on {METRIC})
|
||||
|
||||
*3-5 specific, actionable items grounded in the metrics above. No generic advice.*
|
||||
|
||||
---
|
||||
|
||||
*Generated by `ck:retro` — data sourced from git history only*
|
||||
Reference in New Issue
Block a user