kenlck Weekly Report
Turn a week of commits on one branch into a report a team lead can act on: what was worked on, what changed per country, where the risk is, and who to credit.
Arguments: a branch name, and either a starting commit ref or a date. Both required — ask for whichever is missing rather than guessing. The window runs from that ref/date to HEAD of the branch as of now.
Commit grammar: #<issue number>: <Country> - <message>.
The report is built from dossiers — one fixed-shape record per issue, compiled from that issue's full diff. Everything downstream reads dossiers, never raw diffs. That is what keeps a 40-commit week and a 400-commit week producing the same report.
1. Resolve the window
Fetch the branch, then pin both ends of the window:
- Start: the given ref, or the first commit on or after the given date.
- End: current
HEADof the branch.
Record both full SHAs and their dates. Fail loudly if the branch or ref does not exist — never fall back to the current branch.
Done when: start SHA, end SHA, and both dates are captured verbatim for the report header.
2. Probe the topology
Attribution is the report's most damaging failure — a wrong credit table hands one person everyone else's work. Probe before trusting any author field:
- Merge mode: count merges vs non-merges in the window; check whether commit bodies carry squashed sub-commit lists or
Merged PRprefixes. Classify assquash,merge-commit, ordirect. - Attribution health: compare the distinct-author count against the distinct names appearing in
Co-authored-by:trailers and squashed bodies. Concentration of nearly all commits in one or two authors while many other names appear inside bodies means git authorship is recording who completed the PR, not who did the work.
When attribution is broken, resolve real authors from Co-authored-by: trailers where present, and mark the rest unattributed.
Done when: merge mode and attribution health are classified, and — if broken — the fallback used is recorded. Both go in the report; a reader must never see a per-developer table without knowing which mode produced it.
3. Bucket the commits
List every non-merge commit in the window with SHA, author, author date, and subject. Parse each against the commit grammar into three buckets:
- Issues — keyed by issue number.
- Countries — matched against the table in
COUNTRIES.md. A country field that matches no row goes toUNKNOWN, reported by name so the table can be extended. - Unparsed — anything the grammar does not match. Never discard a commit.
Done when: every commit in the window sits in exactly one bucket, and parsed + unparsed = total. Compute the compliance rate (parsed / total) — it is a reported metric.
4. Enrich from Azure Boards
Best-effort. Try in order until one works:
az boards work-item show --id <n>(needs theazure-devopsextension and a configured org/project).- An Azure DevOps MCP tool, if one is connected.
- Neither — proceed with issue numbers only.
For each issue capture title, state, type, assignee, and created date.
Never stall the report on this step. If enrichment is unavailable, note "tracker enrichment unavailable" in the report header and continue.
Done when: every issue number has either a fetched record or an explicit "not enriched" mark.
5. Compile the dossiers
Fan out one subagent per issue, plus one for the Unparsed bucket. Give each agent: the issue's commit SHAs, the enrichment record, the tripwire list from TRIPWIRES.md, and the dossier template. Instruct each agent to read the full diff of its commits.
Every agent returns exactly this shape, and nothing else:
ISSUE: #<n> — <title or "untitled">
COUNTRY: <canonical>
STATE: <tracker state or "unknown">
COMMITS: <count> by <authors>
FILES: <count>, +<added>/-<removed>
WHAT CHANGED: <2–4 sentences, behaviour not implementation>
TRIPWIRES: <for every tripwire: HIT — <file:line evidence> | CLEAR>
OTHER FINDINGS: <anything real outside the tripwire list, or "none">
VERDICT: GOOD | IMPROVE | MUST-FIX
WHY: <one sentence justifying the verdict>
Rules the agents must follow, passed verbatim:
- Every tripwire gets an explicit HIT or CLEAR. A tripwire left unmentioned is an incomplete dossier — reject it and re-run that agent.
- Every HIT cites a real file path from the diff. A tripwire claim without a file citation is not a finding.
MUST-FIXis reserved for a defect visible in the diff — data loss, broken auth, wrong money, a migration that cannot roll back. Not style, not preference.- Describe only what the diff shows. Speculation about intent belongs nowhere in a dossier.
Done when: one complete dossier exists per issue and one for Unparsed, each carrying a verdict and a full tripwire sweep.
6. Establish the baseline
Glob reports/weekly/ for the most recent prior report on this branch. Parse its metrics table for commits, issues, active developers, compliance rate, per-country counts, and the recorded merge mode.
- No prior report: state "no baseline — first report for this branch" and omit every delta.
- Merge mode changed since the prior report: report the deltas but flag them as not comparable, naming both modes.
Done when: either a parsed baseline with deltas, or an explicit no-baseline statement.
7. Write the report
Write to reports/weekly/<branch>-<YYYY-MM-DD>.md using the structure in REPORT.md, sourced only from dossiers, bucket counts, and the baseline. Do not revisit diffs while writing — if something is missing from the dossiers, re-run that agent rather than filling the gap from memory.
Suppress the per-developer table entirely when step 2 found broken attribution, replacing it with a one-line explanation of what would have to change to make it trustworthy.
Done when: the file exists, every issue from step 3 appears in it, and the header carries the start SHA, end SHA, merge mode, and enrichment status.