/getting-up-to-speed

name: getting-up-to-speed
description: Orients on an unfamiliar or stale codebase at the start of a session, after compaction, or whenever the project state is unclear. Loads beads context, deep-dives the codebase, and produces a structured 'current state' summary. Triggers on phrases like "catch me up", "where are we", "orient me", "what's the state of this project", "bring me up to speed", "load context", "session orientation".

Getting Up to Speed

Orient on the project before any work: re-derive the current state from **ground truth** — commands run THIS session, never memory — and stop for the user's call.

**Announce at start:** "I'm using the getting-up-to-speed skill to orient on the project."

**When NOT to use:** a single targeted question; already oriented this session and nothing changed; a fresh empty repo (use the `project-init` skill).

**frugal bd kernel:** bounded by selection and shape, not by a forbidden call — the memory digest emits a defined tier as short gists, never every body. `bd ready --claim` is FORBIDDEN here — orientation ends at the terminal contract and the user picks the work.

Steps

Copy this checklist into your working response and tick as you go:

• [ ] 1 Gathered (orient.sh + handoff)
• [ ] 2 Explored (path by scale)
• [ ] 3 Drilled (top beads)
• [ ] 4 Closed (capture → prune → archive)
• [ ] 5 Summary emitted through the gate

**Summary-last.** Every tool call and every bookkeeping line lands before the summary; the summary block ends your response, where the user's eye already is.

1 — Gather (at most 2 tool calls)

Run `bash <skill-base-dir>/scripts/orient.sh` once. It emits raw labeled sections: `scale` (tracked=N, git=0|1), `ledger`, `ready`, `in-progress`, `blocked`, `memories` (digest: `key — gist` lines, hazard-class first, then salience >=4), `handoff` (`path=`, `head_sha=`, `doc_sha=`, `doc_mtime=`, `last_commit_time=`, `inbox_count=`). It never runs `bd dolt` commands — orientation stays read-only. If `== handoff ==` has a `path=` line, `Read` that file (the second call); quote only its short headline — never echo doc body sections that could carry secrets. The handoff is a synthesized narrative → cross-check it in step 4 and tag it ⚠️, never "verified".

• No `<beads-context>` block visible this session → run `bd prime` once before the script.
• bd missing / `.beads` absent → the bd sections read SKIP: skip step 3 and the beads lines of the summary; emit "**Beads:** not installed — skipped".

Done when: every orient.sh section is read, and the handoff is read or recorded as "none".

2 — Explore (one parallel batch — never serialize)

Pick the path from `tracked=`:

• **< 40 (Light):** top-level `find`, `git log --oneline -15` + `git status -sb` + top 5 tags, `Read` README.
• **40–150 (Medium, default):** Light + `Read` any of package.json/pyproject.toml/Cargo.toml/go.mod, CHANGELOG/CLAUDE.md/AGENTS.md, project manifests; `find` on skills/agents/docs/hooks/tests/src/lib that exist.
• **> 150 (Heavy):** dispatch two read-only `Subagent (general-purpose)` surveys in one message via the `dispatching-parallel-agents` skill — one reads CLAUDE.md/README/CHANGELOG and returns the architecture in <300 words; the other maps directory layout and per-directory file counts in <200 words. Both briefs are inline — state the scope, the word cap, and "report findings only, change nothing". Then read the 1–3 files they flag. If subagents are unavailable, run the Medium path instead and say so.

Done when: every planned read of the chosen path has returned.

3 — Drill (bounded)

`bd show <id> | head -30` on the top 3 open ready beads by priority — this feeds the "Relevant to ready work" line. The summary table still lists up to 10 from `bd ready`.

Done when: 3 beads drilled (or step skipped with reason).

4 — Close

1. Capture durable, evidence-backed insights: `bd remember "<kind>: <insight>"`. Stale Phase-1 memory → `bd forget <id>`. 2. Prune continuation pointers to one: keep the memory paired with the doc read; forget the rest matching the `continuation-` **key prefix** only. Ambiguous keeper → keep ALL and skip (never guess-delete). Report: "Pruned N superseded continuation pointers; kept `<key>`." 3. Archive the consumed doc (only if one was read; AFTER the prune): `mkdir -p .internal/handoff/archive && mv -f "<doc>" .internal/handoff/archive/` Report "Archived consumed handoff `<name>` → `archive/`." — or on failure "⚠️ could not archive (<reason>); left in inbox" and continue (it self-heals next session). This mv is the skill's only local mutation.

Report all three on a **single short line**, then move to step 5. Skipping any of the three is fine; say which and why on that same line.

Done when: all three are reported (or explicitly skipped).

5 — Synthesize through the gate

Compute the cross-checks yourself (never delegated):

• **Working tree:** `git status --porcelain` + `git diff --numstat`; top-N by churn with `+X/-Y`, binary as `(binary)`, untracked as a count. Never dump the diff.
• **Continuity (in-progress beads only):** base branch from `git symbolic-ref refs/remotes/origin/HEAD` (fallback main/master); `git log --grep="<bead-id>" --oneline <base>` per bead. A hit is **advisory**: `⚠️ <bead> appears in <sha> on <base> — verify it shouldn't be closed`. No commit hit = NOT flagged. Deeper hygiene → point at `bd doctor` / `bd stale`.
• **Handoff freshness (if a doc was read):** compare its stated branch/sha/claims to live git+bd (divergence is advisory), then HEAD-recency from the `@ <sha>` token on its TL;DR branch line:

  DOC="<path>"; HEAD=$(git rev-parse HEAD)
  DOC_SHA=$(grep -m1 -oE '@ *[`*]*[0-9a-f]{7,40}' "$DOC" | grep -oE '[0-9a-f]{7,40}' | head -1)
  # An empty DOC_SHA must never reach the fresh arm: "$DOC_SHA"* would be a bare
  # wildcard matching any HEAD, which is why the -n guard leads every sha test.
  if [ -n "$DOC_SHA" ] && [ "${HEAD#"$DOC_SHA"}" != "$HEAD" ]; then echo fr