git-developer-performance

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

Quick Summary

Goal: Plan and generate a developer KPI-style quality-work report from local git history ONLY, so every effort-point, man-day, and value claim in it rests on inspected diffs rather than commit counts.

Summary: (read-this-if-nothing-else digest — purpose + ALL main steps)

• PURPOSE — turn raw git history into an evidence-backed contribution report. The script collects evidence; AI reads the changes and synthesizes the value — a commit-list export is NOT this skill's output.
• STEP 1 — SET GOAL + PLAN. Declare the goal, trigger $plan, create one todo task per contributor. Large task: NEVER analyze before planning.
• STEP 2 — COLLECT PACKETS. Run the script (defaults: --branch develop→main, --days 60, --out reports/developer-performance). Traverse FULL merged history, not first-parent only.
• STEP 3 — ANALYZE PER CONTRIBUTOR. Read direct authored patches + merge/admin commits from work-packets/*.md. Attribute shared feature-branch implementation to each developer's OWN direct commits — never to the merge author.
• STEP 4 — ESTIMATE via the carried SYNC:estimation-framework (the AUTHORITY, and it OUTRANKS the script's legacy size-based rubric): bottom-up hours → likely_days → EP DERIVED, never assigned from cluster size. Discount generated/docs/lockfile churn FIRST.
• STEP 5 — SANITY-CHECK, then SYNTHESIZE. Velocity plausible vs active days; separate product / infra / docs / merge-admin signal; write quality-work-summary.md + evidence-proof.md outside .claude.
• GATE — run the skill's tests, run the command for the requested range, confirm the output path is outside .claude, before delivering anything.

Workflow:

1. Set Goal + Plan — declare the goal, trigger $plan, create tasks per contributor.
2. Collect Packets — run scripts/git-developer-performance.cjs to build the commit inventory and work packets.
3. Analyze Work — read patches per contributor; estimate value, effort points, man-days, quality impact.
4. Synthesize Report — write quality-work-summary.md and evidence-proof.md outside .claude.

Key Rules:

• Local git history ONLY — NEVER query external services — why: the report must be reproducible from the repo alone.
• Consolidate people by identity map → normalized email → high-confidence alias (DOMAIN\first.lastpart matching a full name); --identity-map handles exceptions — why: raw display names split one person into several.
• Large task — plan FIRST, then one todo task per contributor.
• Script collects evidence; AI reads changes and synthesizes contributed value — why: this is not a commit-list export.
• KPI values are evidence-based estimates, NEVER a complete HR assessment.
• Report BOTH man_days_traditional (no AI) and man_days_ai (AI assistant with project context) — NEVER one ambiguous MD number.
• Traverse full merged branch history, not first-parent only; shared feature-branch implementation credits each developer's own direct commits. Merge authors get integration/admin signal unless conflict-resolution changes were explicitly inspected.
• Estimate implementation EP from direct authored diffs; zero-change merge/admin commits are integration signal only.
• Discount generated files, migration designers, docs/spec output, i18n sorting, lockfiles, and repeated follow-up churn before estimating.
• The carried SYNC:estimation-framework is the AUTHORITY for every EP and man-day figure — EP is DERIVED from likely_days, never from cluster size — and it OUTRANKS the size-based rubric the script embeds in its generated prompt.
• Velocity mismatch or recheck request → synthesize each contributor's direct authored work as one "giant commit" first, then split into atomic 1/2/3/5/8/13 EP clusters.
• Persist large rechecks to a report file outside .claude BEFORE finalizing — why: context loss otherwise erases the evidence.
• Separate product/domain delivery, platform/tooling work, docs/generated churn, merge/admin integration — NEVER mix them silently into one velocity number.
• Velocity sanity check: both man-day ranges plausible for active days and the selected period.
• Keep output outside .claude; default root reports/developer-performance/.