---
name: summarise
description: Generate or update a repository SUMMARY.md that explains what a software project is, what it does, and how it evolved through Git history. Use when the user asks to summarise a codebase, create project history documentation, produce a v3-style management-readable technical narrative, analyse milestones from Git tags, or document significant commits and their product impact.
---

# Summarise

## Goal

Create a `SUMMARY.md` in the repository root unless the user names another file. The document should feel like a polished project-evolution report: technically accurate, management-readable, British English, friendly, crisp, and lightly ADHD without becoming gimmicky.

## Workflow

1. Inspect the project before writing:
   - read high-signal files such as `README*`, package manifests, docs, plugin/app metadata, build files, and the main source tree layout;
   - identify the project type, audience, core capabilities, and current state;
   - do not rely only on commit messages.

2. Gather Git evidence:
   - run `git status --short` and avoid mixing unrelated dirty work into the summary unless it is relevant;
   - list tags in chronological order and treat them as milestones;
   - compare milestone ranges with `git diff --shortstat <from>..<to>`;
   - inspect significant commits with `git show --stat --summary <commit>` and, where useful, `git show --name-only <commit>`;
   - consider merge commits, large diffs, new packages, major docs, tests, security work, UX changes, and architecture shifts as candidates for deeper explanation.

3. Use the helper script when useful:
   - run `~/.codex/skills/summarise/scripts/git-summary-evidence.sh [repo]`;
   - use its output as evidence, not as the final document;
   - inspect extra commits manually when the script highlights something important.

4. Write `SUMMARY.md` with this shape unless the project strongly suggests another:
   - title and short version;
   - executive summary;
   - line-count/change-size table;
   - timeline from Git commits, with tags as milestone headings;
   - what the project does now;
   - architecture and main components;
   - major feature areas;
   - significant commits and why they mattered;
   - security, testing, documentation, and operational maturity;
   - what it is good at;
   - what it is not yet;
   - recommended rollout/readout narrative;
   - final read.

5. Keep the writing honest:
   - distinguish implemented features from foundations, prototypes, and future work;
   - never inflate weak evidence into certainty;
   - call out uncertainty if commit messages are vague;
   - avoid corporate filler, but make it readable for non-specialists.

## Style

- Use British English.
- Prefer concrete product impact over raw technical trivia.
- Explain technical terms briefly when they matter.
- Keep a lively, human tone: direct, warm, occasionally wry.
- Avoid overdoing jokes; one sharp line beats six forced ones.
- Use crisp headings and tables where they help scanning.
- Use exact commit hashes, tag names, dates, and file counts where available.

## Significant Commit Heuristics

Give more detail to commits that:

- introduce or remove a package, service, plugin, app, or major subsystem;
- add a new user-facing workflow;
- change data flow, storage, auth, permissions, or trust boundaries;
- add detector/model/algorithm families;
- introduce a new UI paradigm or configuration system;
- add tests around risky behaviour;
- harden security, input bounds, sanitisation, or error handling;
- create or update major documentation;
- have unusually large line counts or many touched files.

Do not treat every commit equally. A small commit can matter if it changes the product shape; a large commit can be mechanical. Say which is which.

## Output Rules

- Create or update `SUMMARY.md` using normal file-editing tools.
- If a project already has a versioned summary such as `v3.md`, use it as a style reference but do not blindly copy it.
- If the user asks for a specific filename, use that filename instead.
- Include enough detail that a manager can understand the journey without reading the source, while an engineer can still trust the evidence.
- Before finishing, run `git diff --check` if a Git repository is present.