[timeframe] Timeframe
Period to analyze. Accepts 7d, 2w, 1m, sprint, or YYYY-MM-DD:YYYY-MM-DD; defaults to 7d, and sprint asks for a start date when tags cannot define it.
/ak:retro 2026-07-15:2026-07-28 Ctrl K
Quick Ref / Command
Engineer Kit
/ak:retro
Git-history retrospective
Generate an objective engineering retrospective from git history: velocity, churn, hotspots, author activity, plan completion, comparisons, and optional HTML visuals.
01
Parse timeframe
02
Gather raw git metrics
03
Compute derived metrics
04
Check plans directory
Rule 01
Objective metrics beat narrative guesses
Rule 02
N/A is correct when data or tooling is unavailable
Rule 03
Recommendations must cite actual hotspots, churn, test ratio, or activity distribution
Rule 04
HTML visuals are additive; Markdown remains the default
Execution Map
Core lanes from input to output, aligned with the command's real execution path.
01
Start
Input, scope, route
- 1 Parse timeframe Resolve 7d, 2w, 1m, sprint, or YYYY-MM-DD:YYYY-MM-DD into SINCE/UNTIL, and compute the preceding equal-length period when `--compare` is set.
- 2 Gather raw git metrics Run git commands for commits, LOC added/removed/net, hotspots, conventional commit types, authors, active days, unique files, test changes, and per-author counts when `--team` is set.
02
Work
Agent / skill execution
- 3 Compute derived metrics Calculate commit frequency, test-to-code ratio, churn rate, active-day ratio, and GitHub issue plan-completion rate where gh data is available, showing formulas in the report.
- 4 Check plans directory Scan plan Markdown files updated during the period and count completed versus open checkbox tasks for the plan completion section.
03
Verify
Gate, review, validation
- 5 Generate the report Fill the report template with real table values, N/A where unavailable, highlights, 3–5 specific recommendations, and comparison deltas when requested.
- 6 Render optional HTML Save Markdown by default; when `--format html` is set, write a self-contained HTML report and apply the visual preferences or kill switches from the invocation.
Syntax, arguments, subcommands
How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.
Syntax
/ak:retro [timeframe] [--compare] [--team] [--format html|md] [--no-antv|--no-diagram-design|--no-editorial-visuals]Arguments
Shared options
--compare Compare periods
Adds the preceding equal-length period and delta columns. It does not invent deltas when the previous window has no data.
/ak:retro 2w --compare--team Author breakdown
Adds per-author commit counts and team velocity signals from Git email history; review privacy before sharing.
/ak:retro sprint --team--format html|md Report format
Chooses Markdown or self-contained HTML output. HTML uses inline CSS and may include the additive editorial visual layer.
/ak:retro 1m --format html--no-antv No AntV visuals
Disables optional AntV panels for HTML output. Markdown output is unchanged.
/ak:retro 1m --format html --no-antv--no-diagram-design No diagram design
Disables the optional diagram-design treatment for HTML timelines, hotspots, or radar visuals.
/ak:retro 1m --format html --no-diagram-design--no-editorial-visuals No editorial visuals
Disables all additive editorial visual layers for this HTML run; metric tables and formulas still render.
/ak:retro 1m --format html --no-editorial-visualsModes / Routes
default Current period retro
- Research:
- Git history for one timeframe
- Review:
- None
- Validate:
- All cells real or N/A
--compare Delta comparison
- Research:
- Adds preceding equal-length period
- Review:
- None
- Validate:
- Delta column for velocity and health
--team Author breakdown
- Research:
- Per-author commit counts
- Review:
- None
- Validate:
- Team velocity signals
--format html|md Output format
- Research:
- Same metrics
- Review:
- None
- Validate:
- Self-contained HTML or Markdown
Sample Prompt
Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.
Weekly git retro Recommended
/ak:retro 7d- Use when:
- Use to summarize recent engineering history from git activity for a solo repo or team repo.
- Expected:
- Produces the default Markdown report in plans/reports with git-backed velocity, churn, hotspot, activity, test-ratio, formula, highlight, and recommendation sections; unavailable values stay N/A.
Sprint comparison by author
/ak:retrosprint--compare--team
- Use when:
- Use for sprint reviews that need git-history deltas against the previous equal-length period plus per-author activity.
- Expected:
- Resolves the sprint timeframe, asks for a start date if needed, compares against the previous period, adds velocity and health deltas, and includes per-author commit counts without inventing missing data.
Monthly HTML report
/ak:retro1m--formathtml
- Use when:
- Use when engineering history should be shared as a standalone HTML retrospective with the skill's additive visual layer.
- Expected:
- Writes plans/reports/retro-{YYMMDD}-1m.html as a self-contained report with inline CSS, real metric tables, formulas, recommendations, and configured editorial visuals where enabled.
Bounded date-range audit
/ak:retro2026-08-01:2026-08-15--formatmd
- Use when:
- Use to summarize engineering history from git activity across an exact release, incident, or milestone window.
- Expected:
- Uses the explicit SINCE and UNTIL dates, gathers only git and plan facts in that window, computes derived health indicators, and saves the normal Markdown report with N/A for unavailable issue data.
Handled Scope
- Parse timeframe
- Gather raw git metrics
- Compute derived metrics
- Check plans directory
- Generate the report
- Render optional HTML
Artifacts Produced
Retro report
Pattern
plans/reports/retro-{YYMMDD}-{slug}.md or .html Under-200-line retrospective report with metrics, formulas, highlights, recommendations, and optional visual sections.