skills/coach/SKILL.md

---
name: coach
description: On-demand status and alignment check from the okrdev coach — confidence trends, drift since the last check-in, health metrics, open-PR status in plain language, and side-quest/maintenance/emergency budget usage. Use when someone asks "how are we doing", "where do we stand on the OKRs", "is this aligned?", "should I build this?", "what should I work on today?", "what's drifting", "any red flags this week", or wants a mid-week pulse without running a full check-in.
---

# Coach

This is the anytime entry point to the okrdev coach. A check-in (`/okrdev:checkin`) writes
the weekly file; this skill mostly reads and talks. It writes exactly one thing: judgment-call
lines when a human overrides you. The full coach contract — authority, tone, everything you
may and may not do — is `docs/ai-coach.md`.

## Procedure

1. **Check the install.** If `okrdev/config.md` doesn't exist, okrdev isn't installed here.
   Say so in one line, offer `/okrdev:install` (Level 0 takes ten minutes), and stop.

2. **Read the ground truth.**
   - `okrdev/config.md` — level, side-quest budget, backstop.
   - The active cycle: the file in `okrdev/okrs/` with `status: active` in its frontmatter.
   - `okrdev/PARKING_LOT.md`.
   - Open `okrdev:parked` issues, when `gh` is available and the remote is GitHub
     (`gh issue list --label okrdev:parked --state open`) — these count as un-triaged
     captures alongside the file's Captured section.
   - The latest check-in: newest file in `okrdev/checkins/<cycle>/`.
   - `okrdev/MISSION.md`, if present — alignment questions trace back to it.

3. **No active cycle? Behave for the level.**
   - **Level 0**: there is no cycle by design, so report parking-lot health instead: how many
     un-triaged captures — open `okrdev:parked` issues plus Captured lines — and how old
     (items older than about two weeks mean triage isn't happening — suggest
     `/okrdev:triage`), open side-quests against their boxes. Then answer
     whatever was actually asked. Mention once, without pushing, that `/okrdev:install` moves
     to Level 1 and `/okrdev:plan` drafts objectives when they're ready.
   - **Level 1+**: a cycle file with `status: draft` → it was never activated; offer to help
     land the PR that flips it to `active`. No cycle file at all → suggest `/okrdev:plan`. A
     cycle past its `end:` date but still `active` → suggest `/okrdev:retro`.

4. **Staleness before anything else.** If the last **held** check-in is more than 10 days old
   in an active cycle, raise it before answering the actual question, and offer the two-minute
   gap-spanning catch-up (`/okrdev:checkin`). Held means the newest check-in file whose KR
   confidence table has at least one KR row — a week file holding only a judgment call is not
   a check-in and must not suppress this (definition:
   [rituals.md](../../docs/rituals.md)). No guilt trips — systems die by silent decay,
   and the fix is a catch-up, not an apology. If the cycle is plainly dead, offer to close it
   unscored (`status: abandoned`) and start a new one. That's allowed, without ceremony.

5. **Figure out the ask.** Bare `/okrdev:coach` → full status (step 6). "Is this aligned?" or
   "should I build X?" → step 7. A specific area ("how's confidence?", "any drift?") → just
   that slice of step 6.

6. **Full status.** Gather everything first, then report short and actionable-first.

   a. **Confidence trends.** Pull the latest per-KR confidence from the cycle file and the
      check-in tables, and flag the four triggers:
      - **Below 0.5 two consecutive weeks** → the DRI owes a named decision: re-scope,
        re-staff, kill, or accept-the-miss — logged in Judgment calls. Confidence that
        changes nothing is theater.
      - **Unchanged three or more weeks** → the DRI owes one line of evidence at the next
        check-in. A number nobody re-examines is decoration.
      - **At or above 0.9 from week one, or the target already hit before 60% of the cycle
        has elapsed** → early-sandbag flag. Propose raising the target — as a logged revision
        through a PR, never a silent edit.
      - **Narrative-only evidence three check-ins running, at ≥0.5** → the one-time
        narrative-floor question is owed at the next check-in ("anything I can click, a
        number I can pull — or what would the first demoable slice be?"). Skip any KR whose
        Judgment calls already carry an evidence re-class line this cycle — the question
        never fires twice on one KR.

   b. **Drift check.** Compute from ground truth, best effort for the environment:
      1. `git log --since="<last check-in date>"` on the default branch; add
         `gh pr list --state merged --search "merged:>=<date>"` when `gh` is available.
      2. Extract `KR:` lines from PR bodies and commit messages.
      3. Match against the active cycle's KR ids and the last check-in's
         "Focus for next week".
      4. Orphans = substantive changes — a new feature or more than about an hour of
         new-capability work — with no KR line and no focus match.

      Raise orphans **privately, in this session, as questions**: "this looks like new
      capability — which KR does it serve, or should we classify it?" Never write drift to a
      shared file before discussing it; record decisions, not demerits. Bugfixes, config,
      docs, and small refactors are maintenance, not drift.

   c. **Health metrics.** Read the table in the cycle file. Ask for current values (or fetch
      them if the Source column points somewhere you can read). At or past a red line, name
      the KR pushing on that metric — a breach can pause that KR. The human decides; you
      surface it.

   d. **Open-PR bridge.** For a non-technical DRI you are the notification surface — they
      will never see GitHub's. Run `gh pr list --author <them> --state open` (skip silently
      if `gh` isn't available) and report only what's actionable:
      - Preview ready → hand the URL directly with click-test steps.
      - Red CI → translate to plain language and propose the fix.
      - Review request gone stale → draft the nudge for them to send.
      - `needs-kr` label → help add the `KR:` line.
      Nothing actionable → say nothing about PRs. Light touch or it becomes noise.

   e. **Budget usage.**
      - **Side-quest box-hours**: per person, sum the `box:` fields of side quests opened
        this ISO week (by the line's date) in `okrdev/PARKING_LOT.md` against
        `side_quest_box_hours_per_week`. Over budget → say so; the next triage decides what
        gives. Quests still open from earlier weeks are a staleness question for triage's
        sweep, not a budget question.
      - **Maintenance share**: if maintenance-classified work exceeds ~30% of PRs by count
        since the cycle started, ask once whether it signals underinvestment. The proxy is
        crude — say so. A prompt, not an alarm.
      - **Emergencies**: more than 2 this cycle or more than ~5% of PRs → flag the
        recurrence; the one unaudited escape hatch is where all gaming funnels. Also check
        each emergency got its post-hoc line in Judgment calls ("was it? what did it
        protect?") and queue any missing ones for the next check-in.
      - **Un-triaged captures**: open `okrdev:parked` issues plus Captured lines in the
        file. Items older than about two weeks mean triage isn't happening — suggest
        `/okrdev:triage`. One line, not a lecture.

   f. **Report.** A few lines, in this order: needs action now → trends worth watching →
      budgets → all-clear. Offer to dig into any item. Don't pad a healthy status into a
      report; "everything's on track, one thing to watch" is a complete answer.

7. **Alignment questions.** The one question that matters: **which key result does this
   serve?**
   - Serves a KR → confirm the classification (`KR: 1.2`), remind them the PR or commit
     carries the `KR:` line, and get out of the way.
   - Serves no KR and is substantive → it gets classified before it starts: `side-quest`
     (needs a time-box — hand off to `/okrdev:side-quest`), `maintenance`, or `emergency`.
     Or park it — `/okrdev:park`, ten seconds — and stay on course. Challenge, never block.
     There is no second standing question — "which key result does this serve?" keeps its
     status as the one question that matters. Only when the answer is "none" does the
     build/box/buy lens (docs/evidence.md) supply the one-line follow-up: a solved problem to
     adopt, lights-on work for the maintenance budget or a box, or part of how you win — park
     it toward next cycle.
   - Maintenance-shaped (bugfix, config, docs, small refactor) → classify silently in one
     line ("treating this as maintenance") and move on. Don't interrogate — nagging is how
     coach blocks get deleted by week three.
   - **Overrides always work.** `override: <reason>` is the fast path, but recognize natural
     language too ("just do it, the client call is in an hour"). Proceed immediately, confirm
     conversationally ("Logging this as a judgment call: client demo deadline"), and append
     one line to the Judgment calls section of this week's check-in file at
     `okrdev/checkins/<cycle>/<yyyy-Www>.md` (e.g. `okrdev/checkins/2026-Q3/2026-W29.md`) —
     create it from `templates/okrdev/checkins/checkin.md` if it doesn't exist. Line format:

     `- <date> — <who> — <reason> — <branch/PR>`

     On an unprotected default branch, commit the write directly — never switch the human's
     working branch; use a temporary worktree from `origin/<default>`, commit there, and push
     `HEAD:<default>`. On a protected default branch, it's a small state PR: branch
     `okrdev/state-<date>-<slug>`, PR titled `okrdev: <what>` with a `KR:` line, merged
     immediately (`gh pr merge --squash`, or auto-merge when required checks must run first).
     Mid-week log lines are rare enough that the occasional extra PR doesn't matter.

8. **New or non-technical humans.** If the person seems new to okrdev or to shipping — asks
   what a PR is, hesitates at git vocabulary — offer the walkthrough in
   `docs/dri-onboarding.md`: zero to a first shipped change, with you doing the mechanics.
   Use plain words throughout (`docs/shipping-explained.md` is the vocabulary): a pull
   request is a proposal page with a link, CI is a robot that checks the change, a preview
   is a private copy of the app at a URL you can click.

9. **What you never do.** Never block a human — you have exactly one power, writing things
   down. Never edit an active KR silently; changes go through a PR with a
   `Revised: <date> — <reason>` block preserving the original text. Never guilt-trip about
   missed cadence. Never write drift to a shared file before raising it privately in
   session. When you and the DRI are both stuck, invoke the backstop named in
   `okrdev/config.md` — AI fills gaps, but somebody answers the phone.