timeline

Respond in the user's preferred language (detect from their recent messages, or fall back to the language setting in CLAUDE.md).

Arguments: $ARGUMENTS

• No arguments: compare against the default base branch (develop if it exists, else main, else master)
• --base <branch>: specify a custom base branch for comparison

Execution Steps

1. Collect Commit History

git log <base>..HEAD --oneline --reverse --format="%h %ai %s"

2. Group Commits into Semantic Phases

Grouping criteria (in order of priority):

1. Semantic affinity: consecutive commits on the same feature/subsystem go in the same group
2. Natural breakpoints: merge commits, date gaps > 1 day, module switches
3. Phase markers in commit messages: if a commit self-annotates with a Phase, respect that first

Give each Phase a semantic name (e.g. "Player Health System", not "Phase 1"). Target 5–10 Phases (too few loses the timeline's value; too many becomes per-commit annotation); a Phase of more than 15 commits may be split into sub-phases. Grouping is the judgment the whole document rests on — settle it before writing.

3. Analyze Changes per Phase

For each Phase:

git diff <phase_first_commit>~1..<phase_last_commit> --stat
git diff <phase_first_commit>~1..<phase_last_commit> -- '*.cs'

Read the full content of key changed files to understand context — not just diff fragments.

4. Generate Document A: Architecture Evolution Timeline

Format:

# Architecture Evolution Timeline

> X phases, Y commits, Z-day development span
> Branch: `<branch>`, base: `<base>`

---

## Phase 1: <Semantic Name> (<date range>, N commits)

> One-sentence summary

<details>
<summary>Commits</summary>

- `hash1` message1
- `hash2` message2
</details>

### Architecture Changes

#### [Tier 1] Change Title (if any)
**Scope**: ...
**Nature of change**: ...

\```mermaid
<diagram of this phase's changes>
\```

#### [Tier 2] Change Title (if any)
...

### Dependencies Introduced This Phase
- `ModuleA` → `ModuleB` (new reference)

### Cumulative State
> Overall progress to this point: X completed, next phase will Y

---

## Phase 2: <Semantic Name> ...