getting-up-to-speed

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:

``bash 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 fresh elif [ -n "$DOC_SHA" ] && git merge-base --is-ancestor "$DOC_SHA" HEAD 2>/dev/null; then echo possibly-stale else DOC_MTIME=$(stat -c %Y "$DOC" 2>/dev/null || stat -f %m "$DOC") [ -n "$DOC_MTIME" ] && [ "$DOC_MTIME" -lt "$(git log -1 --format=%ct)" ] && echo possibly-stale || echo unavailable fi ```

The verdict is advisory-only; sha absent / no git → unavailable; no doc → "none found".

Then emit exactly this structure. Deterministic sections ((verified)) carry no per-line tags; inferred claims carry [<✅|⚠️|❓> source: <file/cmd>] (+ verify: below high confidence). Sections you cannot fill use the degraded-state language in [references/edge-cases.md](references/edge-cases.md) — never invented.

## What `<project>` Is
<1–3 sentences: language, purpose, lineage.> [✅ source: ...]

## Architecture Highlights
<3–6 sourced bullets with glyphs.>

## Repo Layout (verified)
<code-fenced tree of directories actually present per find.>

## Current State
**Git:** <branch> · <clean | N uncommitted> · <sync vs origin> · latest `<sha>` <subject> · tags <top 5>.
**Working tree:** <top-N +X/-Y · +K untracked> (omit if clean).
**Last release:** <version + CHANGELOG gist; [Unreleased] count>.
**Beads ledger:** <total · closed · open · in-progress · blocked> (verified).
**Continuity check:** <✓ | ⚠️ advisory | skipped | unavailable>.
**Last handoff:** <path> (<date>) — <headline>. Freshness: <✓ fresh | ⚠️ possibly stale — HEAD ahead of <DOC_SHA> | unavailable | none found>.<+N older unread if inbox_count>1>

| Bead | Pri | Title |
<up to 10 open ready beads by priority>

## Recent Activity
<3–5 commits as narrative · in-progress beads · prior thread from handoff. Degrades to "Fresh session — no prior in-session delta".>

**Memory digest (verified):** <the orient.sh `== memories ==` lines, hazard-class first — these are the operational rules that bind this repo>
**Relevant to ready work:** <keyword-scan the remainder against the top ready beads; then read — hits are pointers, not knowledge — quoting full bodies only for hits. Never echo credential-shaped content from a memory body — the same rule as the handoff doc above>
**Remaining:** <total minus digest count> — search `bd memories <keyword>`, fetch `bd recall <key>`

---
<"Welcome back — last thread was <X>." ONLY when the freshness verdict is fresh; if possibly-stale: "Note: the newest handoff (<date>, <DOC_SHA>) predate