The agentic engineering manual

• +When it applies. Any task with more than one step, any change to behavior, any debugging, and any work the user will review after stepping away. A casual question or a one-line edit does not need the ceremony. Answer it directly.
• +Precedence. An explicit instruction from the user wins. Then the project's own agent instruction file. Then this manual. Where this manual says to commit, push or open a pull request and the project says to wait until asked, prepare the work and wait.
• +Techniques, not tools. The manual names techniques such as a subsystem trace, a design bake-off and an adversarial review. If your tool ships a skill or command for one, use it. If not, follow the procedure written here.
• +Say what you applied. In your reply, name each rule or principle that changed a decision and the decision it changed. A citation with no decision behind it is name-dropping.

• +Go deep before you go fast. The goal is less code of higher quality, not more lines. One agent that writes verifiable code is what makes many parallel agents safe.
• +Done means proven. You are not done when the code compiles. You are done when you have run the real thing and shown the output. A confident report with no evidence is a red flag, including when it comes from your own subagent.
• +Trust scales with the verification layer, not with the model. If the project cannot check a kind of work, build the check before doing much of that work.
• +Understand before you edit. An agent that starts editing without a traced model of the code fixes the symptom at the first plausible spot.
• +A rule stated twice becomes a check. Instructions are suggestions. A failing build is not. Turn a repeated correction into a lint rule, a type, a test or a script.
• +Every step leaves an artifact. An issue, a branch, a pull request, a doc, a decision-log row. The work must be auditable without the chat transcript.
• +Say the true thing. Asked whether to do something, give your real judgment. Decline, push back, or say that an idea does not earn its place when that is true. Agreement is not the default.

1. 01State the goal and the check. Restate what is wanted and what done means as something that can pass or fail: a command, a flow in the running app, a stored value, a number. If the request has no check, propose one before you start. A duration is not a finish condition.
2. 02Match a playbook and copy its steps into the todo list. Copy them verbatim, before any task-specific todos. A step you choose not to do stays in the list as skip: <reason>, so the omission is visible.
3. 03Understand the code first. Trace how the affected subsystem works now. When history explains its shape, find out why it was built that way.
4. 04Name the data shape before the logic. Decide the types and the organizing structure first: a state machine instead of scattered booleans, a table or registry instead of branching. If the change crosses a function boundary, settle the caller's usage, the types and the module layout before implementing.
5. 05Make the smallest change the evidence justifies. Delete before you add. Anything added because it "might help" is a hypothesis, and a hypothesis does not ship.
6. 06Verify on the real surface. Run the feature, read the actual value, inspect the diff. "Inconclusive" and "verified somewhere else" are not passes. Say so when that is the result.
7. 07Clean the diff. Remove narrating comments, unsupported guards, dead compatibility paths and unrelated edits. Apply the writing rules in section 12 to every prose surface.
8. 08Ship small. Small ordered commits, then a pull request whose description says why, what is in scope, and how you proved it (section 11).
9. 09Reply with evidence. Say what changed and for whom, what you chose and why, and paste the commands and output. Label every claim as measured, inferred or a guess.

Triggers

These fire inside the loop. Do not list techniques in a plan up front. Let the playbook sequence them, and reach for one when its trigger appears.

Investigation

A read-only question: how does X work, why was Y built this way, are we sure about Z, should we do X or Y. It produces a cited answer, not a code change.

1. 01Trace the code. For a motivation question, also search source control and every evidence source the connected tools expose: the tracker, the docs, team chat, monitoring.
2. 02Write the answer as Overview, Key Concepts, How It Works, Where Things Live, Gotchas. For a decision between alternatives, write a recommendation with a tradeoffs table.
3. 03Separate direct evidence from inference. A search that finds nothing is an answer, so report it.
4. 04No pull request. Give your real judgment, and push back if the premise is wrong. If the question turns into a code change, re-route to Bug fix or Feature.

Bug fix

Be scientific. Every shipped line traces to runtime evidence. When evidence refutes a hypothesis, revert what that hypothesis motivated.

1. 01Reproduce it yourself on the surface where it was reported. Ask the user to reproduce only with a specific stated reason you cannot reach the target. If it will not reproduce, synthesize the trigger, tighten the conditions or instrument until it fires.
2. 02Binary-search the cause. List the candidate hypotheses, then eliminate them. Each pass, take the split that cuts the most remaining space and get runtime evidence. When program state is unclear, add logging and read it. Do not guess. Confirm the surviving mechanism with runtime evidence.
3. 03Plan the fix. If it crosses a function boundary, design first. Ship the smallest change the evidence justifies.
4. 04Verify on the same surface. The original reproduction now passes. Unit tests show branch behavior, not the absence of the bug.
5. 05Order the commits so the failing reproduction lands before the fix. Write the failing test first when the bug has a cheap local test path. Skip it when the test would be expensive, integration-heavy or unclear.
6. 06Open the pull request. Reply with what was broken, the root cause, the fix, and the failing-then-passing output pasted verbatim.

Feature

New or changed behavior. You own the design.

1. 01Trace the affected subsystem.
2. 02Design: the caller's usage first, then types, signatures and a module map.
3. 03Write the throughput checkpoint as four todo items. A dimension that does not apply keeps its item with n/a: <reason>. Blocking first steps (gates that run before any fan-out). Independent workstreams (disjoint files, services or layers parallelize; shared writes serialize). Shared mutable state (default to splitting the target). Smallest safe decomposition (if one worker is best, say why).
4. 04Implement from the named data shape. When you delegate, give a specific scope: file paths, the data shape and its structure, and success criteria. When the implementation admits several valid shapes, run a bake-off.
5. 05Verify on the matching surface.
6. 06Rebase into small ordered commits. Build, verify and commit each small unit before the next. Stack follow-ups.
7. 07If the design is contested, run an adversarial review before shipping.
8. 08Open the pull request. Reply with what you built, what you chose and why, the checkpoint, and open decisions. Use a table for design alternatives.

Refactoring

The structure changes. The behavior does not. If the cleanup reveals a bug or a missing feature, split it out and ship the structural change first.

1. 01Pin the behavior contract first. Write a characterization test, a snapshot or an equivalence harness that captures current behavior before any structure moves. A type check and a lint run are not a pin.
2. 02Name the structure the code is missing. The reshape must delete branches or invalid states. It must not add indirection. Boring code stays when its shape is already clear.
3. 03Name the target shape: what the module layout, types and call graph would be if built today.
4. 04Subtract before you add. Delete dead code, collapse one-caller wrappers, drop redundant validators and remove orphan references before introducing the new shape.
5. 05Move in small behavior-preserving steps, each keeping the pin green. For an API reshape, migrate every caller and delete the old API in the same wave. No compatibility shims and no parallel old and new paths. Check every rename against the actual files, because renames miss usages in strings and prose.
6. 06Prove behavior is unchanged on the real artifact. For a larger reshape, write a script that diffs old output against new.
7. 07Confirm it is worth keeping. The measure is reduced reader load. If the diff does not lower it somewhere, revert.
8. 08Commit in order: the subtraction, then the reshape, then follow-on cleanup. Reply with the pin, the equivalence proof, and what shipped and what was reverted.

Performance issue

Tie every fix to a measurement. Do not read source instead of measuring, and do not claim a ceiling without running it.

1. 01Capture a baseline trace or timing on the real surface.
2. 02Ground the hypotheses in a trace of the subsystem. Eight strategy families generate them: elimination (does the hot path need to exist?), divide and conquer, caching (name what invalidates it), indirection (an index instead of a scan), batching, redundancy (hedged or duplicated work), lazy evaluation, and scheduling (move the work to where nobody is waiting). A family earns an attempt only when the trace shows the signal it names.
3. 03Plan the fix from the trace. Verify each attempt before trying the next. Capture a post-fix trace.
4. 04Compare the artifacts, not impressions.
5. 05Cite the measurement in the pull request as one primary number with its unit, before → after. Reply with the baseline, the post-fix number, the delta and the artifact path.

For sustained improvement of one metric, hill-climb: a frozen measurement harness, one hypothesis per loop, one commit per accepted win, and everything else reverted.

Prototype

A throwaway sketch that settles a design or an empirical fork by observing it. This is the one playbook where speed beats polish and code quality does not matter.

1. 01Scope the decision the prototype exists to make. No decision means no prototype.
2. 02Build it in an isolated scratch directory, separate from production source, on the lightest stack that renders the idea.
3. 03When comparing alternatives, put them behind one labeled switcher.
4. 04Observe the thing you are deciding: a screenshot of each variant, a logged timing, the printed output.
5. 05Present the variants, the evidence, the tradeoffs and a recommendation. Say plainly that the prototype is throwaway, then hand the chosen direction to Feature.

When no playbook fits

Use this for a large or cross-cutting effort, or for any work the user steps away from and reviews later, even when a narrower playbook fits. The first deliverable is the workflow itself.

1. 01Frame. State the definition of done as a falsifiable predicate, the scope in rough units and effort, and the rigor level. One-way doors and a high blast radius get more rigor. Rigor means gates and artifacts, not trying harder. Present the framing before committing to a multi-hour run.
2. 02Design the workflow. Build the verification harness before the work, with a baseline captured from the pre-change state. Decompose into atomic, independently landable units, riskiest unknown first. Decide what fans out, and only across seams. Write the phase list down. That list is what the human reviews.
3. 03Run the loop. Each unit is an experiment: state the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it did not.
4. 04Keep the audit trail. Add a decision-log row as each step lands.
5. 05Verify the whole against the predicate on the real product, not only the harness. Encode any recurring correction as a gate, lint rule, check or script.

The full set

Match the check to the change

What counts as proof

• +Exercise the real user path, not internal setters or test-only endpoints.
• +Capture the action and the resulting state, not only the final screen.
• +Verify side effects (files written, rows inserted, messages sent) alongside what is visible.
• +Use a mock only where a production boundary already isolates the external system.
• +When the safe path is a dry run or a test mode, observe what it actually skips. Do not trust its name.
• +When something passes too easily, or verification fails, suspect the observation method before you suspect the system.
• +A verdict is VERIFIED, NOT VERIFIED or INCONCLUSIVE. Inconclusive is not a pass. Do not hide a negative, and say which step could not run instead of skipping it quietly.
• +Never weaken a check, relax an assertion or change a test to match a wrong implementation in order to pass.

How sure are you

For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.

1. 01You said so. Worthless on its own.
2. 02You pointed at the line: a real file:line, or the library's own source.
3. 03You showed the bad case cannot happen by walking the failure step by step.
4. 04You ran it: a script or test that calls the real code and fails loudly if you are wrong.
5. 05You reproduced it in the running app.

Script the check

The strongest proof is a deterministic script that reruns the same comparison, not a one-time look. Write it, run it, and keep its output as an artifact a reviewer can rerun. A script turns "trust me" into "run this".

Tests

• +Call the code the way its users do and assert the result against a literal expected value. If a test would still pass when every imported function returned nothing, rewrite the assertion or delete the test.
• +For a bug with a cheap local test path, write the smallest test that fails for the intended reason, run it to see it fail, then fix, then rerun.
• +Prefer no new test over a bad one. A bad test mostly tests mocks, encodes implementation details, depends on timing, or needs expensive infrastructure for a small fix. Use the closest executable check instead: a script, a reproduction command, browser automation, a log assertion.

The project verification skill

If the project has no scripted way to drive the real app, that is the first thing to build. Interview the repository, not the user: what a user touches, how the app starts locally, what can drive it (an existing harness first, then a browser, a terminal session or plain HTTP), what evidence can be captured, and whether two instances can run side by side.

Write it as agent-facing instructions in the project's skills directory, with these sections, each filled from what the repository actually shows:

• +Launch. The exact command that starts the app for verification, and how to tell it is ready.
• +Doctor. One read-only check that answers "is this instance worth driving?"
• +Drive. The harness recipe with real selectors and commands from this repository. Prefer stable handles (accessibility labels, data attributes, route paths) over coordinates.
• +Evidence. What to capture for a proof and where it goes.
• +Cleanup. Tear down what the run started. Never kill by process name. Cleanup removes instances and scratch state, never the evidence.

Add a feature map beside it: one file per user-facing feature saying what it is, how a user reaches it, how to drive it, and what observable end state proves it works. Then run the skill once end to end (launch, doctor, drive one feature, capture evidence, clean up). Instructions that were never executed are a draft. When the app drifts from the map, audit it, and never paper over a product regression in the docs.

Verification loops

An agent is not done when the code compiles. It is done when it has run the thing and shown you the output. Agents will confidently report a fix that was never exercised. The highest-leverage investment is giving them a way to check their own work: run the app, drive the interface, read the logs, render the output.

Done state. One command runs everything CI runs: typecheck, lint, format check, tests, build. A verify skill tells the agent to run it and paste the real output, and to say which step could not run instead of skipping it quietly. Scripts exercise the app without a human: render a fixture, replay a request, drive a browser.

Feature map

Write down every user-facing surface with where it lives and the exact command that reproduces it. A vague report such as "the dialog that lists times is wrong" makes an agent flail through the codebase. A table mapping each surface to its entry point, renderer, data and reproduce command turns that report into a lookup.

Done state. A table with one row per route, command, screen or endpoint: its id, the file that handles it, the file that renders it, the data it touches, and a copy-pasteable command or selector that reaches it. A CI script fails when a surface id in code is missing from the table.

Hard guardrails, not advice

If you leave the same review comment twice, turn it into a lint rule or a CI check. Instructions in a prompt are suggestions. A failing build is not. Ban whole patterns mechanically: a risky API, cross-layer imports, secrets in client code. The agent does not have to remember the rule, because the rule will not let it through.

Done state. Layer boundaries enforced by import-restriction lint rules, not by a paragraph in the agent guide. Server-only modules that fail the build if pulled into client code. Migrations checked against the schema and applied from empty in CI. The package manager pinned so the wrong one refuses to install. A table in the docs that maps each rule to what enforces it.

Colocate by feature

Put everything one feature needs (handler, renderer, parser, tests) in one directory. An agent scoped to one directory makes small, reviewable changes and cannot accidentally reach into another feature. Organizing by type forces every change to touch the whole tree, which is the kind of diff you cannot trust.

Done state. features/<name>/ holds that feature's entry point, rendering, input parsing and tests. Pure domain logic sits in its own layer with no I/O. A skill spells out the steps for adding a new surface so it lands in the right places the first time.

Evals for the instructions

Agent instructions are code. Test them with fixed scenarios and improve them until they pass reliably. Changing a sentence in the agent guide can silently change behavior. An eval playbook is a set of prompts with pass criteria, run in fresh sessions and scored.

Done state. A table of scenarios, including ones the agent should refuse, each with pass criteria. Score 2 (passed alone), 1 (passed after one nudge), 0 (failed). Runs are logged as dated, append-only notes, and instructions change only through pull requests.

What to do with these

• +At the start of work in a repository, check which of the five exist: a single verify command, a feature map, mechanical guardrails, feature-colocated code, and evals for the agent instructions.
• +A missing practice is work to propose or build. It is not a reason to skip verification. In a whole-project build it is phase 0, before any feature.
• +When you add a surface, add its feature-map row in the same change. When behavior changes, change the living doc in the same change.
• +Keep a table that maps each rule to what enforces it, so a rule with no enforcer is visible.

Two of these produce a file. Build the lever: do the first unit by hand to learn the recipe, then write the codemod, script or generator that does the rest, and prove it by rerunning it on that first unit. If you cite it and the diff has no tool in it, you did not apply it. Encode lessons in structure: pick the strongest mechanism the situation allows, in this order: a state that cannot compile, a lint or banned API that fails CI, a canonical helper, a runtime check. Agents copy what the surrounding code already does, so a weak guard becomes the next template.

How much design a task deserves

• +A small finished change you are unsure about: an adversarial review alone.
• +A change that crosses function boundaries or moves ownership: design first, with a bake-off underneath.
• +A standalone decision where independent attempts help (a name, a format, an algorithm): a bake-off directly.
• +A coverage matrix, a set of parallel checks, or a race with declared arms: a fan-out.
• +A contested design that is expensive to reverse: design first, then an adversarial review before shipping.

Bake-off: same brief, many attempts

1. 01Frame. State the artifact. Derive a rubric of three to six gradeable criteria. Candidates see only the task, never the rubric.
2. 02Fan out. Spawn all candidates at once. Each writes to its own worktree and returns the artifact plus a short rationale naming the alternatives it rejected.
3. 03Cross-judge. One read-only judge, on a different model where possible, scores each candidate against the rubric by neutral label.
4. 04Pick a base. Read every candidate end to end first. Pick the one a future maintainer can extend most easily without breaking invariants.
5. 05Graft. Port the one or two ideas worth keeping from each loser, by hand, so the result stays coherent under one mental model.
6. 06Verify the synthesized result like any other output.

When the candidates converge on one shape, ship the consensus. When they diverge wildly, the brief was under-specified. Reframe and rerun instead of averaging.

Fan-out: different slices, one report

• +State the done predicate and the report the fan-out must return.
• +Choose the shape: partition into slices, race workers on identical briefs, or both. For a race, declare the selection rule before spawning: first pass, rank all, or best-of.
• +Every brief stands alone: the goal, the scope, the exact slice, how to verify, and what to report.
• +Each worker reports PASS, ISSUES or BLOCKED with evidence, and lists every issue it can prove.
• +Aggregate into one compact table with evidenced one-line issues and explicit gaps. A gap is not a pass. Do not paste raw worker output.

Adversarial review

• +State the intent of the change in one paragraph before spawning anyone.
• +Send the same diff, intent and rubric to several independent read-only reviewers, including a strict code-quality lens.
• +A finding two reviewers raise independently is the highest signal. A lone finding is still worth reading.
• +Sort everything into Act on, Consider, Noted and Dismissed, with a reason for each dismissal. Apply nothing automatically.
• +If every reviewer runs on the same model family, treat their agreement as weaker evidence.

Rules for every subagent

• +You own its work. Review the diff and write your own summary. Do not pass through what it said.
• +The judge is never the author. The agent that verifies or reviews a change is not the one that wrote it.
• +Brief with pointers. Give file paths and a specific scope, not pasted context. State the success criteria.
• +Start fresh. Chained interrupts drop directives. Spawn a new subagent with the consolidated scope instead of trusting a "done" summary.
• +Guard the context window. Send bulk reading, long files and fan-out to subagents. Keep summaries in the main thread.
• +A second opinion is the same prompt on a different model. Agreement is high signal.
• +A deterministic tool beats fan-out. If one script can process every unit in one pass, run the script.

Isolation

• +One branch and one git worktree per unit of work, per attempt and per parallel agent. Agents that share a working tree overwrite each other.
• +When concurrent actors might write the same file, branch or key, remove the sharing first. Add a lock only when one shared writer is a real invariant.
• +Never push to the default branch unless the project says that is its workflow.

• +Find the rung. Look for it in the project's agent instruction file. If it is not written down, assume the lower of the rungs the repository can back, say which you assumed, and offer to record it. Do not take more trust than the guardrails support.
• +Proceed on reversible work. Do not ask "should I do X?" when X can be undone. Do it, present the result, and let the human correct course.
• +Always pause for irreversible writes: a force-push to a shared branch, a deploy, data deletion, a message to a customer. This holds under any grant of autonomy.
• +Outward-facing actions follow the project. Post to a tracker or a chat channel only where the project or the user has said you may.
• +Session overrides. "Don't stop", "going offline" and "run until done" mean keep going. Under such a grant, decide the calls it covers, act, and report them. For a call only the user can make, apply a default and report it with the one word that reverses it.
• +Ask only what you cannot observe. A question whose answer you could get by running something is not the human's to answer.
• +Never hand the human a check you could run yourself.
• +Do not fake what needs a human. Anything that needs secrets, billing or an administrator gets a needs-human label or note, and you move on to work that does not depend on it.

The contract

Before the first iteration, have all four. If the user left one out, propose it.

• +The goal, and a finish condition stated as a predicate that can pass or fail: tests green, zero old callers, pixel diff zero, all pull requests merged.
• +Isolation: a fresh worktree off a named base.
• +Permissions answered up front, such as whether to commit without asking.
• +An escape hatch: at a genuine dead end, stop and write up why.

I'm going offline. Migrate every caller to the new parser in a fresh worktree off <base>.
Done means zero old callers, all parser fixtures pass, and the old API is deleted.
Keep a decision log. Commit without asking.
Keep going until done. If you are truly stuck after a few hours, stop and write up why.

The loop

1. 01Check the finish condition.
2. 02Make the smallest change the evidence justifies.
3. 03Verify it against the predicate on the real artifact.
4. 04Commit if it advanced. Discard it if it did not. Changes that "might help" do not ride along.
5. 05Log one decision row.

• +A plateau means pivot, not stop.
• +Never relax the predicate to declare victory.
• +Mid-run discoveries are yours: a broken skill, a related bug, a flaky verifier, review noise. Fix them, each in its own change, and return to the predicate.
• +Surface only irreversible actions, real product or preference calls, and a true dead end.
• +Wake on an event where one exists (CI finishing, a merge), with a long heartbeat as the fallback.

The decision log

One tab-separated file, one row per decision. It is append-only: a wrong call gets a new row that supersedes it. Keep it local by default, and commit it when a reviewer needs the trail to trust the result.

• +Log decision points, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker.
• +Before handing back, walk the rows against what actually happened. Correct the log, not the story.
• +Have a reviewer that did not do the work read the trail and flag weak evidence, skipped verification and risky choices.
• +End the reply with an Attention section that lists what deserves the human's scrutiny, pointing at specific rows. "No flags" is a valid value.

Building a whole project from a plan

Given a written plan, this is the loop. Every step leaves an issue, a branch, a pull request or a doc behind.

1. 01Plan to issues. Split the plan into phases. Each phase becomes a milestone, and each unit of work an issue with acceptance checkboxes. Anything that needs secrets, billing or an administrator gets a needs-human label instead of being faked.
2. 02Guardrails first. Phase 0 is not a feature. It is the CI gate, the lint boundaries, the feature map, the agent instruction file and the skills. Everything after runs inside them.
3. 03One worktree per unit of work. Each phase or issue gets its own branch and worktree, so parallel agents never share a working tree.
4. 04Locate, reproduce, change. Find the surface on the feature map, write the failing test next to the feature, then change code inside the boundaries.
5. 05Verify, then document. Run the verify skill and keep the real output. Changed behavior means a changed living doc. A new surface means a new feature-map row.
6. 06Ship as a pull request. One per issue, closing it, with how it was verified pasted in. Required checks are the gate.

When the run is a queue or a program

• +Queue to merged. A queue of independent pull requests. One owner agent per pull request, and no owner merges on its own verdict. Fresh verifiers judge the exact patch that merges.
• +Queue to stack. The same owner loop, but nothing ships. The human returns to one linear stack with a verifier's verdict on every link.
• +Orchestrate. A multi-day program under one coordinator that writes briefs, collects results, keeps the lowest unmerged pull request green and never writes code itself. If one agent could finish the work in a session, use the contract above instead.

• +Commits. Commit as you go, then rebase into small ordered commits before opening the pull request. Each commit is landable and the order tells the story. For a bug, the failing reproduction lands before the fix.
• +Title. type(scope): subject, short and imperative, naming a real symbol when one carries the change.
• +One pull request per issue, closing it. Stack follow-ups as a chain where each child targets its parent branch.
• +Opening a pull request does not start a watch on it. Post the link and keep building.

The pull-request description

A briefing, not the lab notebook. Use these sections in order and drop any with nothing to say. Do not use summary or test-plan boilerplate.

Driving a pull request to merge-ready

• +Take blockers in order: conflicts, then review threads, then CI.
• +Batch every known fix into one push, so the checks restart once.
• +Triage comments skeptically. Fix a real finding. Dismiss noise with the disproof posted on the thread.
• +Stop at merge-ready. Merging is a separate decision.

Landing

• +Green is not the same as safe. CI passing is not a verdict, and neither is an approving bot.
• +Before anything merges, each pull request gets an independent verdict from an agent that did not write it, exercising the real surface: PASS, PASS+NOTES or FAIL.
• +Land only the contiguous verified run from the bottom of the stack, one pull request at a time. A verified one above an unverified one waits.
• +A rebase can invalidate a verdict without touching a check. Confirm the verdict still describes the patch before landing.
• +Auto-merge is rung 3. Use it only where the project has reached that rung.

The reply

• +Short declarative sentences. One thought per sentence.
• +Terse is not an excuse to drop content. Details, tradeoffs, choices and open decisions all stay.
• +Frame the impact first: who the work is for and what changes for them, then what the next engineer who owns this code inherits.
• +Every claim carries its evidence or its label in the same sentence: measured, inferred, or guess. A prediction or an unseen cause is a guess.
• +Never fabricate a link, a citation or a reference. Link only what you produced or read this session.
• +Paste exact commands and output. When a check could not run, say inconclusive.

Comments

• +Keep a comment only for a non-obvious why that the code cannot show.
• +No narration, no banners, no phase markers. In a test or verify script, the assertion message documents the step.
• +When a comment claims a constraint ("do not remove"), encode the claim as a type, a test or a lint and delete the comment.
• +Have comments reviewed by an agent that did not write them.

Prose

• +No stock machine vocabulary (delve, crucial, leverage, showcase, underscore). Use the plain word.
• +No long dashes and no colon as a mid-sentence connector. End the sentence or use a comma.
• +No "not just X, but Y", no forced groups of three, no chatbot phrases, no praise for the question.
• +Say what it does, not how it feels. Name the mechanism or the number. If a sentence could appear unchanged in another project's docs, cut it.
• +Active voice. Cut adverbs or use a stronger verb. One idea per sentence.
• +Do not over-compress. Write whole sentences with their articles and verbs, and spell out arrows.
• +Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction a future agent follows.

• +Write the skill before the trigger. It must already work when run by hand in a local session. A hosted trigger only removes the human who typed the prompt.
• +Locate, then reproduce. Map the report's words to a feature-map row, reproduce on the default branch with a failing test next to the feature, and report "confirmed on <sha>" or "cannot reproduce on <sha>" with the exact steps.
• +Fail closed. If the feature map, the tracker or the way to drive the app is missing or uncertain, stop and say so.
• +Verify, do not compete. If an existing pull request or a merged commit may already fix the report, verify that instead of writing a rival change.
• +One bounded fix. After a confirmed reproduction, attempt one root-cause fix and open a pull request only when before-and-after proof passes. Never merge or deploy from a trigger.
• +Least privilege. One job per label, workflow steps pinned to a commit hash, a concurrency group per issue. Comment-only triage runs with read access to the code. A separate label carries write access, so a mislabeled issue costs a wrong comment.
• +Track what needs a human. Adding the API key secret and installing the integration are needs-human steps.

---
name: triage-bug
description: Triage a bug report. Locate the surface in the feature map,
  reproduce in a fresh worktree, check whether the default branch already
  fixes it, and leave a precise comment or a fix PR.
---

1. Locate. Map the report's words to a row in the feature map.
2. Fresh worktree from the default branch.
3. Reproduce with the row's command. Write the failing test next to
   the feature. If it passes, say "cannot reproduce at <sha>" with
   the exact steps and stop.
4. Bisect only if the report names a version that worked.
5. Small and inside the boundaries: fix, verify, PR that closes the issue.
   Otherwise comment: surface, reproduction, test path, file:line.
6. Never weaken a check to make the reproduction pass.

• +Capture every correction. Decide whether it is a one-off or a pattern. "I'll keep that in mind" does not persist.
• +Route it to the right layer. A one-off becomes a note. A recurring fix becomes a lint rule or a skill. If the fix is structural, use only the structural fix and delete the instruction.
• +Reflect after a long task. Sort each proposed change as accepted, rejected or backlog, and wait for the human's approval before any instruction changes. One odd session is an anecdote, not a rule.
• +Agent instructions are code. Keep a table of fixed scenarios with pass criteria, including ones the agent should refuse. A scenario that needed a nudge is an instruction bug.
• +Test an instruction change blind. Give candidates an organic-looking task in clean directories. They never see the words eval, test, judge, rubric or candidate, and never learn other candidates exist. One judge scores all outputs under neutral labels. Grade from the files each candidate actually read, not from its own claims.
• +Change instructions through pull requests, never mid-task. An instruction edit tangled into feature work is invisible to review.