---
name: os-big-picture
description: >-
  ALWAYS invoke this skill when the user asks where the project as a whole
  stands - "where are we", "what's the big picture", "what have we built", "what is in this project", "map the
  project", "what does this thing even do", "what is stale", "what can we
  delete", "update the roadmap" - in any language, and whenever a session
  report has just been written. It keeps one file, BIG-PICTURE.md: what the
  product is, every feature with how far it got, which parts nobody has
  touched, and what is queued next. Age and wiring are measured from git; how
  far a feature got comes from the reports or says "not checked". Where a
  tracker is connected it offers to open the queue as tickets, after a yes and
  never before. Never invents work, never deletes code.
allowed-tools:
  - "Read(~/.claude/open-steps/**)"
  - "Edit(BIG-PICTURE.md)"
  - "Bash(${CLAUDE_SKILL_DIR}/scripts/census.sh *)"
  - "Bash(git rev-parse --git-dir)"
  - "Bash(gh repo view *)"
  - "Bash(gh issue list *)"
  - "Bash(gh issue create *)"
---

# 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`:

```bash
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
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.

## Step 4 - the backlog, sourced and never invented

Three sources, each item naming its own: session reports in
`~/.claude/open-steps/reports/<project>/` (⏳ deferred rows, "Anything needed
from you", recorded debt); Step 3 (each `unused` part, one retire candidate);
the user, by hand. Nothing else - a gap you noticed while reading the code is
not a task, so say it in the chat and let the user decide.

## Step 5 - the tracker, if there is one

An offer, never a quiet action, and only for the "What is next" rows.

1. **Find it, never install it.** `gh repo view --json hasIssuesEnabled -q
   .hasIssuesEnabled`, then any tracker already connected. Nothing connected
   is a normal answer: say so under "What is next", then Step 6.
2. **Search before you propose:** `gh issue list --search '<a few words>'
   --state all --json number,title,state`. A closed ticket is still a match;
   where the search did not run, say so.
3. **Ask, then create.** Plain lines through `os-ask-simple`; on a yes create
   those and nothing else, and only where this pass measured what the item
   rests on. Write each number back into its row, same pass.

## Step 6 - plain words, before it is written

Put every sentence in the block through the `os-say-simple` rules first: one
sentence one idea, active voice, one word for one thing. That covers the prose,
the "What it does" column and the backlog items - never a measured cell.

## The shape

```
<!-- open-steps:begin -->
_Measured <date>. Stages are dated where they stand; anything undated in this
file is not measured._

## What this is

<Three or four sentences. What the product does, who runs it, what it runs
on. No jargon - a reader who has never seen the code.>

## What is in it

| Feature | What it does | Stage | Last worked on | Signal |
|---|---|---|---|---|
| <plain name> | <one line> | live (1 Sep) | 1 Sep | active |
| <plain name> | <one line> | not checked | 28 May | stable |

## Worth retiring

<One line each: what it is, how long unused, what would break. Empty is a
result - write "nothing found" and keep the heading.>

## What is next

- <item> - <source>
- <item> - <source> - #<ticket number, once one exists>

_Age and wiring measured <date>, fresh this pass. Stage comes from session
reports and is only as current as the date beside it._
<!-- open-steps:end -->
```

`Stage` is one of `building`, `built - not shipped`, `live`, `retired` or `not
checked`, and **it carries the date it came from, always** - `live (12 Jul)`,
never bare `live`, and `not checked` never dated. When the newest date in that
column is months behind the newest commit, the reports have stopped: say so.

## Hard rules - these rules *are* the skill

1. **Measured and assumed never mix.** `Last worked on` and `Signal` are
   script output every time. `Stage` has no measurement.
2. **Enumerate, never guess.** The parts come from the script.
3. **Quiet is not dead.** No retire candidate on age alone: quiet plus wired
   in is `stable`, which is what stops the map recommending you delete a
   working product.
4. **Never invent work.** Every backlog item names its source.
5. **Never clobber.** Only between the markers. Their file stays theirs.
6. **Recommend, never act.** No deleting code, moving files, opening a pull
   request. "Worth retiring" is a sentence, not an action.
7. **Plain words.** A feature is named as the user says it, not as the folder.
8. **One screen per section.** Twelve features is a wall - group and say so.
9. **A ticket only after an explicit yes.** Rule 6 is the code, this is
   everyone else's inbox.
10. **The plain-words pass never touches a measured cell.**
11. **Re-measure, never quote.** A number read out of the file is a number
    about the past wearing today's date.
12. **Every claim carries its date or says it has none.** A map that cannot go
    visibly stale will go invisibly stale.

Why the rules are there, the traps the script cannot catch, and a worked
example: [`references/`](references/).