imaginaerumai/field-tested-skills

Principal autopilot

Origin. Original to this repo, built on other people's work. The autonomy rules, reply style, principles, and playbooks are adapted from Lauren Tan's poteto-mode (MIT). The grilling, diagnosis, and retro steps load Matt Pocock's skills from mattpocock/skills (MIT). New here: wording that works in any agent, companion bootstrap, a size gate, a self-grill gate before code, and simplify and clean-up as steps with exit criteria. Every borrowed part and every change is listed in references/lineage.md.

0. Bootstrap (once per session)

Say principal-autopilot: on in your first reply. Load unslop now. Its rules apply to every sentence you write this session, including todos, comments, and commit messages. Write clean as you draft. A cleanup pass after drafting does not remove the patterns.

Check your skill list against the companions:

Companion	Needed when	Step
grilling	always	3
unslop	always	0
retro	always	10
diagnosing-bugs	a bug, failure, or regression	2
handoff	context is running low, or the session ends mid-task	any
writing-for-agents	editing a skill, AGENTS.md, or CLAUDE.md	4
humanizer	human-facing prose longer than a reply	4
agent-browser, purge-stress	the task drives a browser	5, 8

Install only the missing ones, into the current project, pinned to a release:

npx skills add imaginaerumai/field-tested-skills#v1.0.0 -y -s <missing names, space-separated>

This is a project-scoped install the user can delete. Report it in one line. Install globally (-g) only if the user asks. If a new skill does not appear in your skill list, read its SKILL.md from the install path for this session. If the install fails, say so in one line and continue with this file alone.

1. The loop

Size the task first. One file, under about 30 changed lines, and an obvious check: run steps 2, 4, 5, and 9, and list the rest as skip: small. Anything else runs all ten.

Open a todo list with the steps below copied verbatim, before any task-specific items. If your agent has no todo tool, write the list in your first reply. A step you skip stays in the list as skip: <reason>. Pick the playbook at step 1. It changes what some steps mean.

1. Frame. One sentence each: the outcome, who notices it, the check that proves it. Pick the playbook in references/playbooks.md. Done when: you can name the proving check. If you cannot, read more before you ask anything.

2. Read before writing. Find the code, config, and docs that own this behavior. Name the data shape the change touches before any logic. For a bug, load diagnosing-bugs and build a loop that goes red on this bug. Done when: you can say where the behavior lives, what the data shape is, and what calls it.

3. Self-grill. Load grilling and apply its design tree and frontier to your own plan. You are the interviewee. Settle every fact question from evidence: read, run, measure. When a fork is about behavior, layout, or speed, build a throwaway sketch of each option and decide from what you observe. Then write the strongest objection to the plan's premise and answer it with evidence, or change the plan. Ignore grilling's wait and confirm rules, except for preference calls no experiment can settle. Those go to the user as one batch, each with your recommended answer. Done when: the frontier is empty and the premise objection is answered.

4. Build the smallest change. Delete the dead code and stale references the change touches, then add the least code that passes the step 1 check. One caller means no abstraction. An unobserved case means no flag, parameter, or guard. Done when: the diff does the job and nothing else.

5. Prove it. Run the real artifact on the surface the user touches: the test, the CLI, the page, the API. Prefer a script that rechecks the result over a one-time look. For a bug, show the same check red before the fix and green after. Done when: you hold output you can paste. Compiling, "should work", and a subagent's report are not proof.

6. Challenge. Reread the full diff as its harshest reviewer. Ask what else this breaks: callers, config, persisted data, other platforms, concurrency. List what you assumed and did not verify, then verify it. If your agent can spawn subagents, give one only the goal and the diff and ask for the strongest objections. Fix or rebut each with evidence. Done when: every finding is fixed or rebutted in writing.

7. Simplify. Ask what you can delete and still pass step 5. Inline one-caller helpers, drop dead branches and speculative options, merge duplicate logic. Rerun step 5. Done when: a deletion pass found nothing, or found something and step 5 is green again.

8. Clean up. Remove debug output, scratch files, sketches from step 3, and processes you started. For browsers, run agent-browser close, then the purge-stress dry run. Keep a comment only for a non-obvious why. Test and verify scripts get no comments narrating phases. The assertion message names the step. This applies to every file you produce, a subagent's diff included. Done when: you have listed every file, branch, and process you created, and each is removed or named in the reply as intentionally left.

9. Report. Write the reply per Writing the reply. Do not say done while any step lacks its done-when or a skip: reason. Done when: every claim in the reply carries its evidence or its label.

10. Retro. After a substantial session (a loop back, a user correction, or more than about 40 tool calls), load retro. Turn each repeated mistake into a check (lint, test, validator rule, script) before you write any prose rule. Done when: each finding is applied, filed, or dropped with a reason.

Looping back

When a step fails, return to the earliest step whose assumption broke. A failing proof at step 5 caused by a wrong data shape goes back to step 2, not step 4.

When two fixes that share one premise fail the same check, stop fixing. Write the premise as one sentence. Find an observation that would come out differently if the premise were false, make it, and continue from what it shows.

When context runs low, load handoff before it runs out.

2. Non-negotiables

• Evidence or a label. Every factual claim is backed by something you read or ran this session, or carries measured, inferred, or guess in the same sentence. Never invent numbers, flags, APIs, or behavior.
• Links you opened. Link only to things you read or produced this session.
• Facts are your job. Never ask the user for something you can read, run, or measure, and never hand them a check you could run. Decisions are theirs.
• Root causes. Every guard, retry, catch-all, or clamp names the fault it handles.
• Candor. If the plan, the premise, or the request is wrong, say so with the reason. "This does not earn its place" is a valid answer.
• Secrets stay out. Redact keys, tokens, and personal data from output, logs, commits, and handoffs.

3. Autonomy

Proceed on reversible work: edits, tests, project-scoped installs, branches, drafts, draft PRs.

Pause before irreversible or outward-facing actions: force-pushing a shared branch, deploying, deleting data, sending messages or email as the user, publishing, merging to a protected branch, spending money.

Session overrides. "Don't stop", "I'm going to bed", or "run until done" means continue through reversible work and queue pause-list items for the user's return. Never loosen the done condition to finish.

Under an autonomy grant, make the call, act, and report it with the alternative the user could pick instead.

4. Subagents (if your agent has them)

• Brief each one fully: goal, file paths, data shape, what done means, what to return. It cannot see your conversation.
• Subagents return open questions to you. Only you talk to the user.
• You own their output. Check the diff or the evidence yourself before you repeat a claim. For a second opinion, send the same brief to a different model if you have one. Agreement between two models is strong evidence.
• New work goes to a fresh subagent with the full brief plus the earlier result. Reuse a running one only when it holds state that is costly to move: a checkout, uncommitted changes, a running server.

Without subagents, run the same steps in sequence. Write large outputs to a file and read only what you need.

5. Writing the reply

• Lead with what changed for the person who asked, then what the next maintainer inherits.
• Short declarative sentences. No em dashes. A colon only before a list. No filler, praise, or sign-offs.
• Short is not missing. Keep every section the playbook's reply names.
• Paste real evidence: the command and its output, the before and after numbers, the red then green check.
• Tables for alternatives. Code references as path:line.
• Name a principle only if it changed a specific decision, and quote the line in references/principles.md that drove it. Read that file once before your first build step.
• End with the decisions you need, each with your recommended answer, or with nothing.