aicodeking/deepseek-stack

Finish someone else's work as if it were yours, but credit them for what they did.

## Steps

1. Read the source PR, branch or thread in full: description, commits, review comments and any later corrections from the user.
2. Find the real current state: the head SHA, uncommitted changes and open review findings. Treat the handoff notes as hints, not facts.
3. Write down the original goal in one sentence.
4. Choose where to work. By default, make a new branch with the original commits on it and add your fixes as separate commits. Continue in place or stack only if the user asked for it.
5. Run `ds-revive` to bring the work up to date with the base branch.
6. Fix what is needed to reach the original goal. Simplify where you can, but keep every intended behavior.
7. Verify on your own. Reproduce the original problem, then show it fixed. Run the real workflow, not only mocked tests. Record the commands and output.
8. Check the source PR again. It may have changed while you worked.
9. If a PR is wanted, file it with `ds-pr`, then watch it with `ds-watch-pr`. Use `ds-pr-comments` for any reply.
10. Report what you inherited, what you changed, how you verified it, how credit was kept and what is still open.

# ds-best-of-n

One attempt is a sample, not an answer. DeepSeek is cheap enough that three to five attempts usually cost less than one round of fixing a bad first try.

## Steps

1. Frame the task. Write one prompt that every attempt gets unchanged. Write a private rubric of 3 to 6 concrete, checkable criteria. Attempts never see the rubric.
2. Pick N. Use 3 by default and 5 when the design space is wide. Give each attempt its own output location, such as a git worktree or a separate temp folder.
3. Spawn N subagents at once with the prompt, the shared context and their output path. Ask each for the artifact plus a short note on alternatives it rejected. If a harness cannot run subagents, run the attempts one after another in fresh contexts.
4. Check each attempt. Run its build, tests or a quick probe. Record pass or fail with output. Discard attempts that do not run.
5. Score the survivors against the rubric. Pick the one with the best overall structure as the base. Structure beats polish.
6. List the specific strong parts of the other attempts: a test, an edge case, a cleaner function. Graft only those into the base. Do not merge whole files.
7. Re-run the full checks on the grafted result and show the output.

# ds-blast-radius

Listing callers is easy. The job is finding the breakage that a text search will not show, and proving the change is safe with a run instead of an argument.

## Steps

1. Read the change: the diff, the symbols it adds, changes or removes, and the behavior it now has that the diff does not spell out.
2. Find the one or two facts the change is safe because of, for example "this only removes cache entries that are already expired". Most risk clears if that fact holds. Spend your effort here.
3. Look where search stops. Read the source of libraries you call at their pinned version. Check timing: async ordering, teardown, retries. Follow data that leaves the code: API responses, database columns, file formats, config, other languages reading the same data.
4. Grade each key fact by how far you proved it:
   1. you said so (worthless alone),
   2. you pointed at a real file and line,
   3. you traced the failure path and showed it cannot be reached,
   4. you ran a script or test against the real code that fails loudly if you are wrong,

# ds-blueprint

Fix the shape of the code before writing the bodies, so the model fills in a plan instead of inventing one as it goes.

## Steps

1. Ground yourself. Read every module the new code will touch. If you cannot explain how they fit together, run /ds-explain first. Skip this only for code with no surrounding system.
2. Write at least two structurally different sketches. Each sketch is real files with types, signatures, module boundaries and stub bodies that raise "not implemented", plus short pseudocode. Use /ds-best-of-n to produce them in parallel when the design matters.
3. Compare the sketches. Prefer the one with the smaller public surface that hides more inside. Prefer the one where a change that looks right from a single file is also right for the whole repo. Note what you rejected and why.
4. Run the type checker or compiler on the chosen sketch. Paste the output. Stubs must compile.
5. Show the user the chosen sketch and wait for agreement before you fill in bodies. In an unattended run, record the choice with /ds-ledger instead.
6. Implement one stub at a time. After each, run the type checker and the relevant tests. If the sketch turns out wrong, stop and revise the sketch, not just the body.
7. Delete leftover stubs, dead sketches and unused types. Grep for "not implemented" to prove none remain.

# ds-catchup

Bring the user back up to speed in a minute, and hand them every call only they can make.

## Steps

1. Keep this turn read-only. Do not change code, start jobs or post anything.
2. Collect what happened since the user's last message: your own work, subagent reports, and messages from others. Tool notifications are not user messages.
3. Check the current state of anything touched: tests, branches, PRs, running jobs. Use fresh command output, not memory. Fix any number that does not match the source and say you fixed it.
4. Write what changed in under 100 words. Say what it means for the user, for example "the login bug is fixed and its test passes". Leave out hashes, paths and commands unless the user needs one to act.
5. List decisions waiting on the user. A decision is something only they can do: a product choice, an approval, an irreversible action, or access you lack. Include old ones still open. For each give: what it changes, the evidence, the risk, your recommendation, and "unknown" for missing facts.
6. If nothing waits on them, say so plainly.

## Stop when

# ds-context-reset

Store the state of the work in a file, not in the chat, so a fresh context can continue without drift.

## Steps

1. At the start of a long task, create PROGRESS.md at the repo root with these sections:
   - **Goal**: one or two sentences, plus the acceptance check for the whole task.
   - **Done**: the verified steps, each with the command and result that proved it.
   - **Next**: the ordered steps that remain. The first item is the exact next action.
   - **Open questions**: unknowns and decisions that wait for the user.
   - **Key facts**: paths, commands, versions, gotchas, and approaches that failed (with the reason).
2. Update PROGRESS.md after every verified step. Do not update it for unverified ones. Commit the code and PROGRESS.md together with a descriptive message.
3. Watch for reset signals: you repeat an earlier answer, you forget a fact that is in Key facts, you retry a fix that failed, the same file gets reread many times, or the context is more than about half full.

Build a UI that does not look like the default output for any similar prompt.

## Steps

1. Read the brief and the project. Find the subject, the audience, the one action you want the user to take, the stack, the existing brand, and the images you actually have. If the brief is vague, write down how you interpret it in one line and continue.
2. Write a direction note of five lines or fewer before you write code. Include the purpose, the audience, the tone, the one memorable thing, and the mode (persuade, operate, or read). Take it from the subject's own world, not the usual look of its category.
3. Define the tokens before you write components:
   - Type: a display font and a body font that are clearly different. Do not use a default font for display. Use a 5-7 step scale, body text of 16px or more, and lines under 80 characters.
   - Color: 4-6 named hex values. Use one dominant color for large areas and one sharp accent for actions only.
   - Use a 4px or 8px spacing base, one or two radius values, and one shadow style or none.
4. Ask: "Would I make this plan for any similar prompt?" Change each part where the answer is yes.
5. Lay out the page with intent. Choose a density: airy for persuading, compact for tools. Use asymmetry or scale contrast where it serves the content. Use real copy and plausible data. Do not use lorem ipsum.
6. Use motion only where it does a job. Use one orchestrated reveal, plus feedback on user actions.
7. Build every state: hover, focus-visible, disabled, empty, loading, error, and long content.

Score a UI from what is on the screen, fix the worst problems, and show that the fixes work.

## Steps

1. Identify the target file or URL and render it. If it does not render, report this and stop. Do not audit from the source code alone.
2. Take screenshots of the first viewport and the full page at about 1440px and 390px wide. Also capture the hover, focus, empty, loading, and error states where you can.
3. Read the target's code: tokens, fonts, colors, focus styles, media queries, and copy.
4. Give each area a score from 1 to 5. Give one line of evidence for each score: something visible or a line of code.
   - Hierarchy: the main message and action are clear within 3 seconds, and there is one focal point.
   - Typography: the fonts are paired on purpose, the scale is consistent, and the line length and leading are correct.
   - Color: there is one dominant color and one accent, the colors are tokens and not scattered hex values, and there are no decorative gradients.
   - Spacing: the spacing follows a scale, the rhythm is consistent, and the mobile alignment is correct.
   - States: hover, focus, empty, loading, error, and long-content states all exist.
   - Accessibility: the contrast is 4.5:1 or higher, the focus rings are visible, the fields have labels, the touch targets are 44px, and reduced motion is respected.

# ds-explain

Give one plain account of what a thing is, how it runs, and why it has its current shape, so the reader can change it with confidence.

## Steps

1. Work out what the reader needs. Read the conversation: are they about to change it, review it, debug it, or are they new? Pick the three or four things they should walk away knowing. Skip what they already know.
2. Size the job. A single function needs one pass. A subsystem across many files can use two to four parallel read-only subagents, each on one angle, then one pass to combine them.
3. How it works. Read the actual code. Trace the main runtime path from entry point to effect. Note who owns each piece of state and where the boundaries are. Cite files and lines.
4. Why it is that way. Check commit history, blame, PR descriptions, linked issues and comments near the code. Separate what the record says from what you infer, and label inferences clearly. If no record exists, say so.
5. Write the explanation. Start with a plain definition in general terms, then tie it to this codebase. Walk through what happens when someone actually uses it. Then the reasons, then the edge cases. Use a small diagram or table when it helps.
6. Offer to go deeper on one named part.

## Stop when

# ds-help

Match the task to one skill, say why in one line, then run it.

## Pick a skill

| If the task is... | Use |
|---|---|
| Any coding session (always on) | ds-mode |
| Vague or high stakes | ds-sharpen, then ds-plan-loop |
| More than one file or step | ds-plan-loop |
| A new module or API shape | ds-blueprint |
| Any code change | ds-verify-loop |
| A bug with a cheap test target | ds-tdd |

Get two or three independent reviewers to judge the same change, then fix until they agree.

## Steps

1. Get the work ready first. Answer open PR comments, fix known issues and run the relevant checks. Skip this only if the user wants to throw the code away.
2. Pick the jurors. Use models the user named. Otherwise pick the strongest available model from two or three different providers, at high reasoning effort.
3. Find a way to reach them in this harness: team workers or subagents with a model setting, a second agent CLI in the terminal (for example a Codex or Claude CLI), or an API call. If only one model is available, start two or three fresh-context subagents of that model, each with a different persona: correctness, security and edge cases, simplicity and scope.
4. Write one brief for all jurors: repo path, base SHA, diff command, goal in one sentence, out-of-scope items and check results. Tell them to review only and change nothing.
5. Ask each juror for: a verdict (APPROVE or CHANGES), a score out of 10 and findings as `id severity file:line claim fix`. Severity is blocker, should or nit.
6. Run the jurors in parallel. Wait for all of them. A timeout or error is not approval.
7. Check each finding against the code yourself. Fix the ones you agree with, with the smallest change. Write a one-line reason for each one you reject.
8. Re-run checks. Start a new round with the same brief, your answers and the new diff.
9. Report the result. If there is a PR, edit its description and add a table: juror, model, score per round. Write `no score` when a juror gave none. If there is no PR, put the table in your final reply.

# ds-ledger

A long run forgets its own reasons. A short written ledger keeps the goal in view and lets a reviewer trust the result.

## Steps

1. Create one TSV file, for example `.ds-ledger.tsv`, with the header `ts	phase	decision	why	evidence	result`. Put the goal and done condition in the first row.
2. Before each step, re-read the goal row and the last ten rows. Check that the next step still serves the goal. If it does not, log the drift and correct course.
3. After each real decision, append one row:
   - ts: ISO 8601 time.
   - phase: the phase or workstream.
   - decision: what you chose or did, one line.
   - why: the reason in plain words.
   - evidence: a pointer, never prose. A commit hash, `file:line`, a command and its result, or an artifact path.

# ds-lessons

An instruction an agent can skip is a wish. Make repeated mistakes fail loudly instead.

## Steps

1. Gather mistakes. Read the current session, recent commits, reverts, review comments, agent instruction files and workaround comments. Group them into classes. A class counts once it happened twice.
2. For each class, pick the highest level that works:
   1. Structure: one owner per piece of state, one supported way per task, hidden internals, delete old patterns an agent would copy.
   2. Types: make the bad state impossible to write.
   3. Lint or CI check: the error message names the right file, type or function to use. If the bad pattern is already common, fail only on new additions.
   4. Test: checks behavior, not internals.
   5. Docs or agent rules: only for judgment calls that cannot be checked. Add a short example of the failure.
3. Fix the most frequent classes now, one commit each.

# DeepSeek working mode

Apply this on every task. It keeps the loop tight and the claims honest.

## Before you act

1. Restate the task in one line. Say the goal and the smallest change you expect to meet it. Do not wait for approval.
2. Read the code you will touch before you edit it. Find every caller of a function before you change its behavior.
3. If the evidence shows the requested change is wrong, show the evidence and stop.
4. For work with more than two steps, write a short numbered plan. Each step ends in something you can check. Use ds-plan-loop for anything larger than a few files.

## While you work

- Make the smallest diff that solves the problem. Delete before you add. Do not add layers, options, or helpers that nothing needs yet.

# ds-plan-loop

Plan before coding, check the plan once, then build the task one verified step at a time.

## Steps

1. Restate the goal in one sentence. List the files and commands you expect to touch. Read those files before you plan. Do not plan from memory.
2. Write a numbered plan. Each step gets one action and one acceptance check that a command or a direct observation can confirm, for example "`npm test -- auth` passes" or "`GET /health` returns 200". Keep each step small enough to verify in a single diff.
3. Write the plan to a file (PLAN.md, or the PROGRESS.md from ds-context-reset) so later steps and fresh sessions can read it.
4. Critique the plan in a fresh pass. Reread only the goal and the plan, as a reviewer who did not write it. If you can, run the critique in a subagent or new session. Answer three questions:
   - Which step is missing (setup, migration, config, tests, cleanup)?
   - Which assumption has not been checked against the code or docs?
   - Is there a simpler path that reaches the same goal with fewer steps?
5. Revise the plan. Check each risky assumption now by reading code or running a command. Do not carry it forward as a guess.

Open one real PR whose title and description a busy reviewer can read in ten seconds.

## Steps

1. Check if a PR already exists for this branch (`gh pr list --head <branch>`). If it does, update it.
2. Diff the branch against its base, usually `origin/main`. Confirm the diff matches the goal and holds nothing unrelated.
3. Read the titles of a few recently merged PRs and copy their format.
4. Write a title that says what changed for the user and why it matters, not which function moved. Example: "Cut websocket frames by 70% with compression" beats "Negotiate permessage-deflate".
5. Write the description in this order:
   - The problem, in one or two plain sentences taken from the user's request.
   - The fix, in one or two sentences.
   - One line on how it was proven, if you have proof.
   - A closing line: `Created with <model> in <harness>.` Use the model name the harness reports. If it reports none, name only the harness.
6. Scan the title, body and any attachments for secrets, tokens, private paths and personal data. Remove them.

Make every agent-written comment easy to spot, short and safe to publish.

## Steps

1. Write the reply. Lead with the conclusion. Cite the code line, check, test or reproduction that supports it. Mark what you verified and what is your opinion.
2. Put this note at the top, with the reply below it:

   ```md
   > [!NOTE]
   > **<model> responding on behalf of <user>**

   Reply text starts here.
   ```

# Engineering principles

If a trigger matches, apply the rule. Name principles that changed a decision.

## Design

1. **Subtract, then add little.** Remove dead code and stale checks first, then make the shortest diff that works. No abstraction with one user. Apply when sizing a diff or tempted to add a layer.
2. **Data shape first.** Choose the core types and structures before logic. Apply before writing new logic.
3. **Model the domain.** Put states in one structure, such as a typed union, state machine, or lookup table, not scattered conditionals. Apply when code branches a lot or repeats a shape across files.
4. **Redesign for the new need.** Fit a new requirement as if it existed from day one. Apply when an addition strains the design.
5. **Low reader load.** Inline one-caller wrappers and shrink mutable scope. Apply when code is hard to trace.
6. **Guards at boundaries.** Validate where input enters: CLI, config, network, files, external APIs. Trust types inside and keep core logic pure. Apply when adding validation or error handling.
7. **Idempotent steps.** Rerunning a step, even after a crash, reaches the same state. Apply to commands, setup, and retries.
8. **No shared writers.** Give each concurrent actor its own file, branch, or key before using locks. Apply when parallel work touches shared state.

Do all of `ds-ship` except the merge. Hand the user an open PR that passes the merge gate.

The request grants the same test permission as `ds-ship`, and you may commit, push, rebase and `--force-with-lease` this task's branch. You may not merge.

## Steps

1. Read `ds-ship` and follow its steps 1 to 6: branch, change, prove, review, file, watch.
2. Before the first push, turn off auto-merge and take the PR out of any merge queue. Check again before each push. If you cannot stop automatic merging, report that before you continue.
3. After the last fix, re-prove any behavior change and any non-trivial conflict resolution.
4. Fetch the base branch. Read the live PR: head SHA, base, checks, reviews, mergeable state. Confirm it is open and not a draft.
5. Apply the `ds-ship` merge gate and pick one verdict:
   - **Ready**: the gate passes. Leave the PR open.
   - **Waiting on approval**: only a required human approval is missing. Confirm that this is the real blocker.
   - **Blocked**: say what stops it, what you tried and what is needed.

Make a change more correct by letting one fresh reviewer push back until you both agree.

## Steps

1. Scope the change. Run `git status --short`. Do not stash, discard or include unrelated files. Find the base: `git fetch origin`, then `git merge-base HEAD origin/<base branch>`. Use one diff command for every round.
2. Write the goal and out-of-scope list in two sentences. Run the covering checks. Do not send code that fails them.
3. Pick the reviewer: a stronger model if the harness can reach one (subagent with a model setting, team worker, second CLI), or else a fresh DeepSeek context with no history. Record which one.
4. Send this brief:

   ```
   Review only. Do not edit, commit, push, comment or start subagents.
   Repo: <path>  Base: <sha>  Diff: git diff <sha> [-- <paths>]
   Goal: <goal>  Out of scope: <list>  Checks: <results>
   Read the code around the diff. Find bugs, broken callers and gaps against the goal.

Update the idea, not only the branch. A clean rebase does not prove the PR still belongs.

## Steps

1. Fetch the latest base, the PR head and any related branches.
2. Record the PR URL, state, base, head branch, head SHA, author, checks and review state. Read the title, body, linked issues, commits, threads and full diff.
3. Write the PR's goal in one sentence.
4. Find the merge base. Read what landed on the base branch since then. Search merged and open PRs for the same problem.
5. Answer each question with evidence (commit, PR or file path):
   - Has this problem already been solved?
   - Did the APIs, types, schemas or structure it relies on change?
   - Was the code it edits moved, deleted or simplified?
   - Would landing it bring back old behavior or make two ways to do one thing?
   - Is the benefit still worth the upkeep?

# ds-sharpen

A sharper prompt saves more tokens than any loop. Fix the ask before doing the work.

## Steps

1. Restate, in your own words, what the user wants and the problem behind it. Keep it to three sentences. If you cannot, ask one question.
2. Deepen the task. Answer briefly:
   - What would a top professional do here that the user did not ask for?
   - What raw material would they start from, instead of a summary?
   - What methods and tools would they use?
   - What outside check, not you or the user, would show the result is right? Name a command, test, metric or source.
3. Rewrite the prompt to ask for exactly that. Keep it no bigger in scope. Leave choices that belong to the user open and list them.
4. Optional stress test, when the plan is risky or the user asks. Spawn two or three subagents with fresh context and give each the plan and the goal. Ask each to break it and back every finding with a run: a failing test, a probe script, or real command output. Drop findings with no run behind them.

Own the work from its current state to a merged PR while nobody is watching.

Only act this way when the user clearly asked for it. The request grants three things: run the tests and app checks the proof needs without asking first, force-push this task's own branch with `--force-with-lease`, and merge once the gate below passes. It grants nothing else.

## Steps

1. If you are on the default branch, create a new branch.
2. Make the smallest change that meets the goal. Fix the case that was reported, not every case that might exist.
3. Prove every part of the diff. Reproduce the failure, apply the fix, and run the same reproduction again. Run the checks CI runs. For UI or runtime behavior, run the app and look. Paste the command and its output into your notes.
4. Review the change with `ds-review-loop`. Re-prove anything the review changed.
5. Rebase on the latest default branch, then file the PR with `ds-pr`. Add one line that says how you proved it.
6. Watch the PR with `ds-watch-pr`. Fix real findings and CI failures, prove each fix, push, and watch again.
7. Check the merge gate on the latest commit. Merge with the repo's usual method. Never use `--admin` or any other bypass.
8. Report the PR link, merge commit, proof, and every decision you made for the user.

# ds-swarm

Split work that is wide but shallow across parallel workers, then merge their proven results into one report.

## Steps

1. State the done condition and the report the swarm must return.
2. Pick the shape. Partition the job into non-overlapping slices, or race N workers on the same brief, or both. For a race, decide up front how you will choose: first pass, rank all, or best one.
3. Write one brief per worker that stands alone: goal, exact slice, how to verify, what to report. When workers test specific commits, name the exact commit hashes and the measurement method.
4. Give every worker that writes files its own output location.
5. Spawn all workers at once. If the harness cannot run subagents, run the briefs one by one in fresh contexts.
6. Each worker reports PASS, ISSUES or BLOCKED with evidence: commands run and their output. ISSUES lists every provable issue, not just the first.
7. Collect results. Reject any result with no evidence or the wrong commit and respawn that worker once. A second miss is a recorded gap, not a pass.
8. Merge into one report: the verdict, each slice or arm with its evidence, gaps, and duplicates merged by root cause.

# ds-tdd

Make the bug executable before touching production code, so the fix is proven, not claimed.

## Steps

1. Pin down the bug: expected behavior, actual behavior, the code path, and the smallest way to reproduce it.
2. Find the nearest existing test style for that code path. Use it. Do not build a new harness just for this.
3. Write the smallest test that would have caught the bug. It checks intended behavior, not the current implementation.
4. Run it. Show the output. It must fail, and fail for the bug, not for a typo or missing import. If not, fix the test first.
5. Make the smallest production change that gives the intended behavior without breaking nearby contracts.
6. Run the new test and the surrounding suite. Show the output.
7. If a clean test is impractical (heavy setup, brittle mocks, production-only state), use the closest runnable check instead: a script, a repro command or a log check. Say why you skipped the test.

# Unslop

Write clean as you draft. Then scan for these tells and rewrite. Keep the meaning and tone.

## Tells to remove

Words
- Inflated vocabulary: delve, crucial, pivotal, robust, seamless, leverage, utilize, showcase, underscore, tapestry, landscape, testament, vibrant, intricate. Use the plain word.
- "Serves as", "stands as", "boasts". Say "is" or "has".
- Abstract metaphor nouns: paradigm, north star, flywheel, substrate, bedrock. Name the concrete thing.
- Adverbs that prop up weak verbs: "significantly improves". Give the number or a stronger verb.

Sentences
- "Not just X, but Y." State Y.

# ds-unstick

When two fixes fail the same way, the problem is usually a wrong belief, not a wrong edit. Find that belief and test it.

## Steps

1. Stop editing. Do not try a third variation of the same fix.
2. Write down each failed attempt in one line: what you changed and what happened. Include the exact error text.
3. Write the assumption that all of those attempts shared. Typical examples: "this file is the one that runs", "the config is loaded", "the function receives a string", "the cache is cleared", "the error comes from my code". Name one, in one sentence.
4. Test that assumption directly with the cheapest probe that gives a yes or no answer: a print statement, a log line, a `which` or `--version`, a grep for the real call site, a minimal script, or a read of the docs for the exact version installed. Paste the result.
5. If the assumption is false, you have found the real problem. Plan the fix from the new fact.
6. If the assumption holds, list 3 different approaches. "Different" means another mechanism, library, layer or data path, not a tweak of the same edit. Give each approach one line on cost and risk.
7. Pick one approach and say why in one sentence.
8. Restart from a clean state if the failed attempts left debris: revert them with git (`git stash` or `git checkout -- <files>`), then apply only the chosen approach.

# ds-verify-loop

Prove a change works by running the real check and fixing what it reports, not what you expect it to report.

## Steps

1. Pick the check before you edit: the narrowest real command that proves the change, such as one test file, a typecheck, a build, or a run of the app with one request. Write the command down.
2. Run it once before the edit if you can, so you know the baseline (already failing, already passing, or broken for another reason).
3. Make the smallest edit that should satisfy the check.
4. Run the exact command. Read the full error output, including the first error, the file and line, and the stack frame in your code. Do not skim to the last line.
5. State the root cause in one sentence, based on the output. If you cannot, add one print or log line, or read the failing code, and rerun. Do not guess.
6. Fix the cause, not the symptom. Do not add a special case for the one input that the test uses.
7. Rerun the same command. Count this as one iteration.
8. When the narrow check passes, run the wider one once (the full test suite, the build, or a lint) to catch breakage elsewhere.

Keep one PR moving until it is green and reviewed, with as little noise as possible.

The watcher is `scripts/watch_pr.py` in this skill's folder. Call it by absolute path. It needs `python3` and a logged-in `gh`.

```bash
python3 <skill>/scripts/watch_pr.py <pr> [--repo owner/name] [--until ready|green|any] [--interval 30] [--max-minutes 60]
```

It prints one line per new check failure, finished check run, comment or review, then a final `stop:` line. Exit 0 means the condition is met or the PR merged. Exit 1 means you must act. Exit 2 means bad input. `ready` waits for green checks, a mergeable branch and no change request. `green` waits for checks only.

## Steps

1. Handle what already exists: failed checks and comments newer than the last push.
2. Start the watcher. Run it in the harness's background or monitor tool if it has one, so each line wakes you. Otherwise run it as one long foreground command.