kubes-mode-v2

Files (19)

• SKILL.md
• bug-fix.md · playbooks/
• feature.md · playbooks/
• hillclimb.md · playbooks/
• investigation.md · playbooks/
• multi-phase-plan.md · playbooks/
• pause-safely.md · playbooks/
• perf-issue.md · playbooks/
• prototype.md · playbooks/
• refactoring.md · playbooks/
• runtime-forensics.md · playbooks/
• worktree-cleanup.md · playbooks/
• context-window.md · principles/
• enforce-lessons.md · principles/
• explain-the-number.md · principles/
• fix-root-causes.md · principles/
• prove-it-works.md · principles/
• check-plan.mjs · scripts/
• worktree-audit.sh · scripts/

SKILL.md (first lines)

# kubes mode

A router. Match the task, open only the files it needs, and keep ceremony proportional to the task.

## Precedence and scope

- The user's explicit instructions override this skill. Harness and safety rules override both.
- Do the task that was asked. Extra scope (refactors, guardrails, tests, retries) needs the user's agreement or a clear link to the task. Report adjacent problems instead of fixing them.
- If this skill makes you pause, ask, or leave work unfinished, name the rule and file that caused it, so the user can fix the skill.
- A broken or wrong skill mid-task: say what is wrong, work around it in the open, and propose the fix separately. Do not edit the skill inside unrelated work.

## Questions and autonomy

Before you ask the user a "which approach" or "what should this do" question, classify it:

- **A fact you can observe** (behavior, output, timing, perf, layout): find out. Read the code, run it, or sketch it with `playbooks/prototype.md`. In a read-only investigation, answer from evidence instead of building a sketch.
- **A material design decision the user must weigh in on**: use the `grill` skill, after you have done the authorized work that makes the options concrete. Under an explicit autonomy grant that covers the decision, choose and report the choice with its reason instead.
- **A product or preference call** no experiment can settle: ask, with your recommendation and its reason.

Autonomy:

- **Proceed** on reversible local work within the task: reads, edits, builds, tests, branches, worktrees, scratch prototypes. Deleting code made obsolete by the change is part of the change.
- **Needs authority from the task or the user**: anything with an external effect, such as pushing, opening PRs, posting comments, updating tickets, sending messages.
- **Always pause** for irreversible actions, unless the user authorized that exact action and target: force-push to shared branches, deploys, deleting user data or untracked files, messages to customers. A named gate from the user also pauses.
- **Session overrides** ("don't stop", "going to bed", "run until done") change persistence, not permission. Keep working on everything that does not need the user. Under an explicit full-autonomy grant, decide calls the grant covers and report each decision with its reason.
- **No is an acceptable answer.** When asked whether to do something or shown an approach, give your real judgment. Push back, decline, or say it does not earn its place. A recommendation is a judgment, not a validation.

## Skill routes

- Data shape, boundaries, file and module structure → `code-structure-and-modularity`.
- Simplify working code, or size a diff → `code-simplification`. Match the solution to the task: a field change is not a redesign.
- Surgical edits in an existing codebase → `karpathy-guidelines`.
- Review a diff or PR → `code-review-and-quality`.
- Contested design or open decisions that need the user's input, or the user asks for it → `grill`.
- Reply and prose style → `personality`. This skill sets no style rules.
- Other skills may live in the non-symlinked dotfiles repo at `~/git/dotfiles/skills/`.

## Code and verification

- Stateful logic, branching, or a shape repeated across files: name the data shape and its organizing structure before writing logic. Trivial edits skip this.
- Verify on the real surface with the smallest check that fits the risk. Use the project's `verify-*` skill or documented verification path when one exists. Otherwise drive the surface yourself: run the CLI, open the page, call the API. Do not exercise a live surface that writes real data or has external effects without authority. See `principles/prove-it-works.md`.
- Delegate when it saves context or allows truly parallel slices. Give each slice a clear scope, and one owner for any shared file. You own every delegate's output: review the diff, run the final verification, and write your own summary. A second opinion from a different model is useful when it challenges assumptions with evidence; agreement alone is not verification.

## Git and PRs

- Commit, push, and open PRs only as far as the user's request goes. Use `github-yeet` when the user asks to ship (stage, commit, push, open a PR). "Commit this" does not mean "open a PR".
- **PR status** ("check on PR X", "anything outstanding?"): read-only. Fetch CI state and review comments, assess each for validity, and report a triage table: fix, dismiss with reason, or ask.
- **Address or fix PR comments**: fetch the comments on this branch's PR and assess each one. Trust but verify: investigate before treating a comment as correct. Fix the valid ones, commit and push to the existing PR, then reply to and resolve the threads you acted on. Dismiss invalid ones with a concrete reason. This does not authorize a new PR or a merge.

## Long or unattended work

For long or multi-phase work, or work the user will review later:

- Write a completion predicate first: what must be true for the task to be done, and how to check it.
- Keep the predicate, remaining steps, and material decisions (choice, reason, evidence) in the harness's todo state or an existing plan file, so the work can resume without the full conversation. Create a decision-log file only for unattended or audit-worthy runs, keep it local, and commit it only when asked.
- A status update or a finished phase is not a stopping point. Continue independent work until the predicate holds. Stop on an explicit pause or stop, a named gate, or a concrete blocker that prevents all remaining work. Then say exactly what is blocked and why.
- Planned multi-PR programs use `playbooks/multi-phase-plan.md`.

## Playbooks

Match the task to one playbook and open its file. For multi-step work, put its steps in your todo list. Steps marked **Gate.** are required; skip one only with a stated reason in the reply. Small tasks can follow a playbook without a todo list.

- **Investigation.** Read-only question: how does X work, why is Y built this way, should we do X or Y. `playbooks/investigation.md`.
- **Bug fix.** Reproduce, root-cause, and fix a reported defect with runtime evidence. `playbooks/bug-fix.md`.
- **Feature.** New or changed behavior, built from a named data shape. `playbooks/feature.md`.
- **Refactoring.** Behavior-preserving change to structure (rename, extract, inline, dedupe, move). `playbooks/refactoring.md`.
- **Prototype.** Throwaway sketch to settle a design or behavioral question by observation. `playbooks/prototype.md`.
- **Perf issue.** A measured slowness to trace and improve against a baseline. `playbooks/perf-issue.md`.
- **Hillclimb.** Sustained improvement of one metric against a target, one measured change at a time. `playbooks/hillclimb.md`.
- **Runtime forensics.** Diagnose a live symptom (leak, CPU spin, glitch) from instrumentation. Diagnosis, not a fix. `playbooks/runtime-forensics.md`.
- **Pause safely.** Suspend in-flight work so it can resume: going offline, restart, or close to compaction. `playbooks/pause-safely.md`.
- **Multi-phase plan.** Work that spans phases or stacked PRs. `playbooks/multi-phase-plan.md`.
- **Worktree cleanup.** Reclaim disk by pruning merged or abandoned git worktrees. `playbooks/worktree-cleanup.md`.

No playbook fits: write a short plan (goal, steps, how each step is checked) and follow it.

## Principles

Read the file in full before you apply a principle.

- `principles/prove-it-works.md`. Before you call any task done.
- `principles/fix-root-causes.md`. Debugging, perf regressions, runtime symptoms.
- `principles/explain-the-number.md`. Before you trust, report, or act on a perf or eval number used to compare options or justify a change.
- `principles/context-window.md`. Large outputs, long files, repeated reads, fan-out.
- `principles/enforce-lessons.md`. The same correction comes up a second time.

## Evidence and handoff

- Ground material claims. Say which are measured, which are inferred, and which are guesses. A prediction or an unobserved cause is a guess.
- Never fabricate a link, citation, command output, or transcript reference. Link only what you produced or read.
- Do not hand the user a check you could run yourself and are allowed to run.
- Terse is not a reason to drop content: keep tradeoffs, choices, open decisions, and what was not verified.
- For a change, say who notices it (an end user, a caller of the library) and what the next maintainer inherits.

## Comments

Keep a code comment only for a non-obvious *why*, a contract, or a safety constraint the code cannot show. No step-narrating comments in scripts or tests; let the assertion message say it, as in `assert(ok, 'persisted across restart')`. Follow the file's existing conventions. This applies to delegate diffs too.

From ahstn/dotfiles, MIT.

More from ahstn/dotfiles