worktreereview

Files (6)

• SKILL.md
• collect.py · scripts/
• render.py · scripts/
• review.py · scripts/
• timing.py · scripts/
• writer-handoff.md

SKILL.md (first lines)

# Worktree review

Turns one worktree's logs into a report the owner can read: a clock chart, a stage table with list
prices, a drilldown per stage, tokens and cost by model, the Codex passes, and what the
reviewer makes of it. The two scripts do every number; you write only the words.

## When it runs

Only when the owner asks: `/worktreereview <unit>`, for a merged build or one still running. The merge
step does not run it, and nothing else starts it (the owner, 2026-10-14).

The page of computed numbers alone, with no words from you, is one command that uses no model:
```
python3 ${CLAUDE_PLUGIN_ROOT}/skills/worktreereview/scripts/review.py <worktree path> --no-open
```
It collects, renders, files the page under
`~/.commandeck/reviews/<date>/<project>/<unit>-review.html` and prints that path as its `page:` line.
The page flags a build past a threshold. Defaults: more than 30 minutes of Codex review in total;
more than a third of the clock on tests or idle waits when those also come to more than 10 minutes, the
flag naming the largest single command; more than 30 US dollars at list price (`--max-review-min`,
`--max-test-share`, `--max-usd`; the owner's answers at setup, saved as `reviewLoop` in the project
config, replace these defaults). A wait on a review pass run outside the Builder's session (the owner
ran it) or on a review tool that was down has its own slice of the clock and counts toward no flag.

It reads logs only, so it works after main has removed the worktree:
- the Claude session logs filed under the worktree's path (`~/.claude/projects/<path with - for />`),
- the helper logs beside them,
- every Codex session record whose working folder is the worktree (`~/.codex/sessions`).

## Steps

1. **Find the worktree path.** It is `~/orca/workspaces/<project>/<unit>`. If unsure, list
   `~/.claude/projects/` for the unit name. The folder need not exist any more.

2. **Collect.**
   ```
   python3 ${CLAUDE_PLUGIN_ROOT}/skills/worktreereview/scripts/collect.py <worktree path>
   ```
   It prints the stages, totals, clock split, Codex passes and guard refusals, and writes
   `result.json` and `notes.txt` to `/tmp/commandeck/worktreereview/<project>/<unit>/`. Stages are automatic:
   Build, then each Codex pass and the fixing between passes, then Wrap-up.

3. **Split the Build stage when it covers several jobs.** Read `notes.txt` (the agent's own
   progress notes with UTC times) and find where it moved from one issue to the next and where
   building turned into its own checks. Run collect again with one `--split` per boundary:
   ```
   --split "21:22:54=Build the two slow hooks" --split "22:08:11=Own checks before review"
   ```
   A split within a minute of the start renames the first stage. Say in the report that the
   boundaries are yours.

4. **Read what the numbers cannot tell you.** If the worktree still exists, read its evidence
   file (`.claude/briefs/<unit>-evidence.md`), above all "Not done / not checked". Read the
   Codex findings in `result.json` (`passes[].message`). Check whether main has merged it
   (`git log` on main, read-only) and what main said in the inbox.

5. **Write `notes.json`** next to `result.json`. Keys: `title`, `summary`, `stage_notes`
   (by stage code), `pass_findings` (by pass number, one plain sentence each), `lessons`
   (title and points), `not_measured`, `method`, and `shrink_review`: one entry for each
   "Where it could shrink" item, by its bold title, marked covered by an open issue
   (`{"item": "Long thinking", "issue": "#12"}`, citing it) or uncovered with a one-line
   proposed fix (`{"item": "Long thinking", "fix": "..."}`). The page lists the marks and
   names any item left unmarked.

6. **Render and check.**
   ```
   python3 ${CLAUDE_PLUGIN_ROOT}/skills/worktreereview/scripts/render.py <result.json> <notes.json> <out.html>
   ```
   Every figure you quote in a lesson must match the page's tables. Recompute, do not recall.
   The page computes the "Where it could shrink" items, so the first render may list some under
   "Not reviewed yet": add a `shrink_review` entry for each and render again.

7. **File it** where your role files reports for the owner and add the index line.

8. **Open it in Orca**, in the worktree the owner reads reports in, as a rendered page:
   ```
   orca-ide tab create --url "file://<absolute path to the html>" \
     --worktree "path:<that worktree>"
   ```
   Confirm with `orca-ide tab list --worktree "path:..." --json` that a tab carries the
   report's title. (`orca-ide file open` only takes files inside the worktree and shows the
   source, not the page.) Then give the owner the clock split, the cost and the lessons in a few lines.

## Time waiting on the owner is cut

Time a Builder sat waiting on the owner is not build time (the owner, 2026-10-14). collect.py cuts it
from every clock figure, share and flag, and leaves cost as it is: each `--exclude START=END` window
(ISO UTC, repeatable; review.py passes it through), and the part of each idle gap over two minutes with
nothing of the build running that sits inside an open decision in the main checkout's
`.claude/metrics/decisions.jsonl` that names the unit in its `source` or `answer` (the last row per
decision and ask wins). A gap waiting on main or on nothing with no decision recorded is cut whole, and its
reason names the cause. Idle after the Builder's `<UNIT>-DONE` line is not cut by itself: with no owner
decision open it stays on the clock, as does time waiting on a merge. A gap with any session's background
job or a Codex run in it is kept, and a found window cuts only idle seconds. Overlapping windows cut
each second once. Once the worktree is removed nothing proves which checkout it came from: pass `--main <main
checkout>` (review.py passes it through), or no decision and no round archive is read. Still counted, and the page says so: a helper's request and tool subtotals, and
command seconds inside a cut Codex pass. The page and `result.json` (`cut`, `cut_s`) list every window with its start, end,
length and reason.

A hold main recorded with `unit-hold.sh <unit> hold|release '<reason>'` is cut the same way, reason `hold`,
except seconds a Codex run or background job covers. A stretch with no session open, no Codex run and no hold, as
long as an owner wait or longer, is listed in an "Unexplained idle" box (`result.json`: `unexplained`,
`unexplained_s`) and is not counted in any stage.

## The two timing sections

Every page carries them, computed, with no words needed from you:
- **Time off Claude's servers**: tools, hooks, Codex and waiting. What it was, commands grouped
  by the script they ran, hook time before and after each tool call, each logged hook, each
  idle wait, the inside of each Codex pass, and every tool call in a sortable table.
- **Time on Claude's servers, request by request**: the wait before the model began, thinking
  and writing; by what the request did, by stage, by context size and by reply size; the
  slowest requests; every request in a sortable table; and "Where it could shrink", a computed
  list (single looks sent one at a time, the fixed cost of a round trip, long thinking, long
  replies, advisor consults, cache writes, repeated commands, time-limit kills, refusals).

Each "could shrink" figure is a ceiling the code worked out, not a ruling. Use them as leads:
sort the tables, check the rows, and only then write a lesson.

From pushprove-max/Commandeck, Apache-2.0.

More from pushprove-max/Commandeck