os-big-picture

os-big-picture

One file, BIG-PICTURE.md, where os-whats-next already looks for a backlog. It answers "where are we now" - not a plan, nothing in it a promise. Write it in the user's language; paths stay English.

When to use it. The user asks where the project stands, or there is no BIG-PICTURE.md yet → the full pass: describe, census, signals, backlog. A session report was just written → the fold-in: only the rows that session touched. Both re-measure, because a session that moves no row is the one after which the dates go quietly stale.

Step 1 - find the file, and never clobber it

BIG-PICTURE.md in the project root, and it may already be somebody's own work. Everything this skill writes lives between <!-- open-steps:begin --> and <!-- open-steps:end -->; no markers → append at the end; no file → create it, and add it to this clone's ignore list, never to .gitignore:

f=BIG-PICTURE.md; e="$(git rev-parse --git-dir)/info/exclude"
git check-ignore -q "$f" || git ls-files --error-unmatch "$f" >/dev/null 2>&1 \
  || grep -qxF "$f" "$e" 2>/dev/null || printf '%s\n' "$f" >> "$e"

Each of the three is a reason to leave it alone. Say in one line that you did it; git add -f BIG-PICTURE.md shares it instead. Never read Last worked on or Signal back out of the file - only Stage and the queue carry forward.

Step 2 - the census, measured by the script

bash "${CLAUDE_SKILL_DIR}/scripts/census.sh" .

An AGE line, then one measured PART row per part: path, last worked on, commits in six months, whether anything outside reaches it, the signal.

Step 3 - reading what it printed

Signal	What it means	What to do
active	Being worked on	Nothing
stable	Quiet, and something still reaches it	Leave it alone - finished and in use
unused - N months	Quiet, and nothing reaches it	The only real retire candidate

When the AGE line says young, write one line directly above the table, before the header row: "This project is N days old. Nothing here can be quiet for six months yet, so the Signal column will only start to mean something from the date the script gave." Every active is then a fact about the calendar, not the code. On an ok line, write no such note.