Exec Status

exec-status

Keep one file — STATUS.md at the run's working-directory root — that a CEO with zero context can open mid-run and, in ~30 seconds, answer: What is this trying to do? Is it going well or badly? What has it actually found? What's next? Should I be worried? The reader doesn't read code, logs, or this conversation — the report is their only window, so its job is not to summarize your work but to translate the state of the run into plain outcomes a smart outsider can trust.

Core job: close the gap between agent-speed work and human-speed oversight. The run produces detail faster than any human will ever read, so STATUS.md is the single bridge across that gap — a deliberately lossy-but-faithful roll-up: keep what changes the stakeholder's decision, risk, confidence, or next expectation; drop detail that only proves you were busy; never drop uncertainty that would change the answer. Write at the reader's decision altitude, not the agent's execution altitude — every line should help them answer what should I now believe, decide, watch, or stop worrying about?

Governing philosophy — BLUF Pyramid, driven by CCIR, managed by exception

The shape isn't ad hoc; it's the briefing canon — naming it gives you a tie-breaker for what to cut:

• BLUF / Pyramid — answer first, then a few reasons, then evidence: Health + Bottom line carry the decision, What we've found so far gives the few supporting reasons, Checked against / Confidence is the evidence layer. (This is why ~3 findings, not a log.)
• CCIR — surface or update information only when it changes what the reader would believe, decide, watch, or worry about. It's an information filter, not a maintenance reminder.
• Managed by exception — routine progress stays compressed; you escalate through Should you be worried? and Needs a human? only when the run leaves safe bounds or needs a decision.

Bootstrap — do this before substantial work

On the start or resume of any qualifying run (see the description), before you dig in:

1. Look for STATUS.md at the working-directory root.
2. If it exists, read it first and reconcile it against the actual durable state (the files/commands its For the AI section names), then refresh it before continuing. After a context reset the report is the only memory that survived — trust it only after you've checked it against reality.
3. If a qualifying run is already underway and no STATUS.md exists, create one now. The trigger isn't only at t=0.

This bootstrap is the compaction defense at work: the file survives the reset on disk, and re-reading it re-engages the discipline — but only once the file is actually reopened (see Surviving a long run).

The file

One STATUS.md at the working-directory root (the project you're working in), rewritten in place — never an append-only log. It is a derived view of durable state (results files, commits, run logs, your notes), never the source of truth — so it's always safe to regenerate from reality and it never feeds back into the work. Commit it or leave it untracked, your call; either way treat it as a projection you can overwrite at any time. If the working dir is $HOME or has no project boundary, this skill doesn't apply — there's no durable run to brief on. If an existing STATUS.md looks hand-edited or corrupted, treat it as stale and re-derive every section from durable state.

Scaffold a new STATUS.md with the helper script below (or copy the template from this skill's assets/STATUS.template.md). A report a CEO can trust earns that trust three ways, and the template is built around them:

• Visible freshness. The top line carries Health + Fresh as of, and a How current is this block states Last checked against: (the durable evidence the report reflects) and Out of date if: (the concrete condition that means something newer happened). A skill can't run on a timer, so "always current" is impossible to guarantee — but the file can at least tell the reader exactly when to stop trusting it.
• Evidence-tethered claims. Every finding names a handle a skeptic could check and a confidence label, so "going well" can't be asserted without backing.
• An alarm it's allowed to sound. A standing "Should you be worried?" line that can say yes. An all-clear is only believable from a report structurally able to raise a red flag.

Keeping it current

There's no background timer — a skill is instructions that run while you work. So tie updates to events you can't miss because they're already part of the work, not to a clock. Refresh STATUS.md when the stakeholder's decision surface would change — what to believe, whether to worry, whether to continue or change course, whether a human is needed, confidence in a finding, or what result you're waiting on: a finding lands / is reproduced / is overturned; a phase or experiment completes; a blocker appears or clears; the Health verdict would change; before a long-running command (say what's running and what result will update the report) and after it finishes. If none of those would change, do nothing — most work events warrant no update, and narrating busywork is the failure, not the goal. The human owns no maintenance burden: your job is to earn their silence, so they never have to ask "what's the status?" and only ever read the file or answer a specific Needs a human? ask.

• The freshness trio travels together. Whenever you update content, also update Fresh as of, Last checked against, and Out of date if. Never bump the timestamp without re-checking the evidence boundary — a fresh-looking report over a stale boundary manufactures false trust, which is worse than no report. If you can run the helper, docmaint stamp --attest rechecked --checked-against … --out-of-date-if … writes the three together and records a checkpoint, so a later un-attested edit is caught by check --handoff.
• Edit the changed section in place, don't rewrite the whole file — anchor on the section heading. That keeps upkeep cheap on a long run. Reserve a full rewrite for a reconcile.
• Full reconcile (re-derive every line from durable state): on start/resume, at a phase boundary (setup → baseline → main loop, or a task handoff), and — since you have no persistent timer — whenever control returns from a long unattended command, plus at natural handoff points after a batch of meaningful steps — ask whether the bottom line, worry level, findings, next step, or human-needed answer changed, and if not, leave it — so drift gets caught even in an unbounded loop without busywork edits.
• Keep the For the AI section current. When the evidence boundary shifts (new result files, new commands, new checkpoints), update its reconciliation checklist — it's the map the next model uses to recover after a reset.

Writing it so a CEO trusts it

• Gloss every term on first use — including in the header lines, where the 30-second scan starts. The first time a model / dataset / method / metric appears, give it a ~4-word plain gloss, then use it freely. Jargon isn't banned; it's paid for on entry.
• Tether findings to evidence, with an honest confidence label. Define the labels so they can't inflate: early = seen once / not reproduced; moderate = reproduced once or corroborated by independent evidence; strong = reproduced under the intended comparison and not contradicted by known failures. Never write "improved / solved / on track" unless the evidence supports it.
• Pick Health honestly. ON TRACK only when there's an explicit success criterion and current evidence supports it; UNKNOWN when the goal, baseline, or evaluation isn't established yet; WATCH when evidence is mixed or thin; BLOCKED when stuck; DONE when the stated goal is met and verified against a named evidence boundary. In open-ended research there is often no "track" yet — say so.
• Default toward WATCH/UNKNOWN; make ON TRACK and DONE the claims that must be earned. Silence filled with hope is the exact failure the reader is exposed to, and an LLM's bias runs optimistic — a run that always reads green is a warning sign, not a success. Promote to ON TRACK only when current evidence meets the success criterion; until then, say UNKNOWN.
• Translate, don't duplicate. If autoresearch.md / TODO.md already hold the technical state, lift the meaning into plain outcomes — don't paste experiment rows or checklist items, and don't keep two copies of a fact that will drift. Point at the other file instead.
• At most one Progress: line — never a checklist. ## Where we are may carry a single optional Progress: line, but only when the run has a finite, decision-relevant scope (e.g. 7 of 10 services migrated; the 3 left include the only high-risk one — full checklist in TODO.md). Count outcomes, not activity ("3 of 4 gates passed", never "ran 47 commands"); keep it to one line with no sub-bullets — the moment it wants nesting or per-item status it has become an operator checklist and belongs in todo/TODO.md, not here. Cite the durable source in Last checked against:, and omit the line entirely for open-ended or exploratory work, where a forced or stale count manufactures the false precision this section exists to avoid.
• The busy test. If a sentence only proves you were busy rather than what it means for the reader's next decision, cut it — outcomes and their decision implications only, never activity for its own sake.
• One screen, and a snapshot — not a log. It's a fixed-size briefing you overwrite, never a growing record: when a new finding outranks an old one, replace it (keep findings to ~3); there's no history section by design — history lives in your commits and results files. Before calling an update done, strip every <placeholder> and instruction phrase, then re-read only the first screen as if you'd never seen the project: if you can't answer what / how's it going / what's been found / what's next / should I worry without one unexplained term, fix the report, not the reader.

Don't overlap

STATUS.md is the human-facing briefing — not the operator checklist (todo / TODO.md), the experiment-recovery state (autoresearch.md), or a reformat of your last reply (digest). When those exist, update STATUS.md at the same checkpoints they're updated (one cadence, not a competing one), write only CEO-facing sentences into it, and let each file keep its own job.

Optional helper

scripts/docmaint (in this skill's own directory) is a stdlib-only helper that todo, exec-status, and mental-seal all share with the same verbs — locate · scaffold · check · sync · stamp · print · self-test (exit 0 ok · 1 stale under --handoff / missing under --required · 2 malformed). It does only the deterministic parts — never prose — and auto-locates STATUS.md by searching upward to the project/git root (pass --path for a run-specific file below the repo root):

• scaffold — write the template to STATUS.md if it's missing.
• check [--handoff] [--required] [--max-lines N] — verify the required sections (including For the AI) and freshness fields are present, Health is valid, no <placeholders> remain, and the report hasn't bloated (warns past ~one screen, fails past ~2×); warns (nonfatally) when a finding names no Checked against: handle or Confidence: label. It also checks the freshness checkpoint (below): a stale or never-attested Fresh as of is a warning by default, a failure under --handoff. Run docmaint check --handoff as the gate before you leave the run unattended or after a full reconcile — not as routine ceremony.
• sync — refresh only a hidden, mechanical validated_at comment after structure passes; it never touches prose or the visible freshness fields.
• stamp --attest rechecked --checked-against "<evidence>" --out-of-date-if "<condition>" — the only verb that moves Fresh as of. It sets the whole freshness trio together (Fresh as of → now, plus Last checked against and Out of date if — both required, so the trio can't half-update) and records a content-hash checkpoint over the report, including the visible Fresh as of. This is how auto-stamping stays honest: the tool writes the timestamp, but only inside your explicit attestation that you re-checked the evidence — and any later edit (even a hand-bumped timestamp) makes check --handoff fail until you re-stamp. The checkpoint is tamper-evident, not tamper-proof: it catches honest drift and accidental edits, not an agent that deliberately recomputes and rewrites the hidden hash. Run it only after you have actually re-checked the evidence boundary.

The skill works without the script — it's an accelerator, not the mechanism: the format above is documented, so an agent that can't run it maintains STATUS.md by hand (write the freshness trio yourself, moving the timestamp only when you re-checked the boundary). The script never invents freshness — a bare check/sync will not move Fresh as of; only an attested stamp does. docmaint self-test verifies the helper.

Surviving a long run

A skill is just instructions, so a context compaction can summarize away the instruction to keep STATUS.md current. The defense lives in the file, not in any harness machinery: the report survives on disk, the bootstrap has you read it on resume, and its For the AI section restates the full discipline — so a model that reads it re-learns how to keep it current even with the skill gone from context. The honest ceiling: nothing portable forces the reopen, so a fully hands-off run never re-triggered between compactions can still drift — but the Out of date if: line keeps that drift visible, and any model that reopens the file can recover the discipline.

Worked example (what a filled first screen looks like)

# STATUS — Teaching our spam filter to catch more fake reviews

Health: WATCH — best version beats the baseline, but the win is small enough it might be noise · Fresh as of: 2026-06-17 14:32 PT

## Bottom line
We're trying to catch more fake product reviews without wrongly flagging real ones. It's going okay: the
newest approach catches noticeably more fakes, but we're not yet sure the gain is real rather than luck.

## Should you be worried?
Mildly. The improvement has only shown up once — if it doesn't hold on a fresh batch of reviews (checking now),
the win may evaporate. No outside blocker.

## What we've found so far
- **Looking at *how* a review is written, not just the words, catches more fakes** — about 1 in 6 we used to miss.
  Checked against: experiment 21 in results.tsv. Confidence: moderate (beat baseline twice).
- **Bigger models didn't help** — the win came from better signals, not more horsepower. Saves money later.
  Checked against: experiments 8–12, all flat. Confidence: strong.

## Where we are
- Done: built the test setup; ran 21 experiments; found a clear front-runner.
- Now: re-checking the front-runner on reviews it has never seen.
- Next: if it holds, lock it in and write up.
- Needs a human? No.

## How current is this
Last checked against: experiment 21 in results.tsv, commit a1b2c3d.
Out of date if: results.tsv has experiment 22, or the fresh-batch run started at 14:30 has finished.

## For the AI — skip if you're the human
- You're maintaining this as a live plain-English briefing — a snapshot you overwrite, not a log; on resume, reconcile every section against reality before continuing, then keep it current (replace stale findings, don't accumulate).
- Update when a stakeholder answer changes (finding lands/reproduced/overturned, phase ends, blocker shifts, Health changes); edit the changed section and move the three freshness lines together; full reconcile on resume and when a long command returns.
- Health/confidence honestly: ON TRACK only with a met success criterion; early = seen once, moderate = reproduced/corroborated, strong = reproduced under the intended comparison.
- Check before trusting/continuing: results.tsv, run.log, git log --oneline -5