Operating policy output style / model instructions
The assistant stops narrating and reports once, with evidence. Same task, different transcript.
# assistant transcript- Great question! Let me first look at the code...- I found the issue! Now let me fix it...- The fix is applied. Let me run the tests...- Tests pass! ✅ Let me know if you need anything else!+ Fixed the race in queue.ts:41 — the worker read the batch+ before the lock was acquired. `npm test`: 214 passed, 0 failed.
software-engineering base layer, always loaded
Root cause over symptom. A retry loop around broken logic preserves the defect — the skill forces finding why it fails.
def load_config(path):- for _ in range(3):- try:- return json.loads(open(path).read())- except Exception:- time.sleep(1)+ with open(path, encoding="utf-8-sig") as f:+ return json.load(f) # the file had a BOM — retrying never helped
software-architecture boundaries and ownership
Domain logic stops depending on transport. Pricing rules no longer import an HTTP client.
- def apply_discount(order):- rate = requests.get(RATES_URL).json()["vip"]- return order.total * (1 - rate)+ def apply_discount(order, rate):+ return order.total * (1 - rate) # the caller at the boundary fetches the rate; the rule is now testable
api-design contracts that survive
No more HTTP 200 with an error inside. Status codes and error shapes become part of the contract.
- return jsonify({"ok": False, "msg": "not found"}), 200+ return jsonify({"error": {"code": "user_not_found",+ "message": "No user with id 42"}}), 404
debugging reproduce, then fix
Sleeps that hide races are banned. The failure gets reproduced and the ordering fixed.
- await new Promise(r => setTimeout(r, 500)); // flaky fix- expect(cache.get("user")).toBeDefined();+ await warmup; // the promise the test never awaited+ expect(cache.get("user")).toBeDefined();
verification evidence before "done"
Completion claims must be backed by checks that actually ran in the session.
- Done! The migration should work now.+ Migration applied and verified: `alembic upgrade head` succeeded,+ `pytest tests/test_orders.py` — 31 passed. Rollback tested with+ `alembic downgrade -1` on a copy of the schema.
test-engineering test behavior, not internals
Tests assert observable behavior and cover the edge that actually broke, deterministically.
- assert parser._tokens[3].kind == 7+ assert parse("price: -0.00").price == Decimal("0")+ assert parse("price: 1e999").error == "overflow"
planning plan before code
Complex work starts with acceptance criteria and a validation strategy, not with the first edit.
- *starts rewriting the auth module in message one*+ Done means: existing sessions survive the deploy, login p95 < 300ms,+ `test_auth.py` green. Steps: extract token store → dual-read window →+ switch writes → remove legacy. Rollback: flip AUTH_STORE env back.
agent-delegation the right agent for the job
Big tasks split across scoped subagents with disjoint file ownership instead of one overloaded context.
- one context: reads 80 files, plans, edits, reviews itself+ codebase-analysis maps the call sites (read-only)+ executor implements within src/billing/** only+ verifier runs the checks and reports pass/fail with output
project-documentation one source of truth
Docs stop duplicating what code already declares — they link to it and stay current.
- ## All 47 CLI flags explained (copied, stale since v2)+ Run `mytool --help` for the full flag list.+ Common workflows: [deploy](docs/deploy.md), [rollback](docs/rollback.md)
web-research verify, don't recall
Versioned facts get checked against primary sources, with dates, instead of answered from memory.
- Next.js supports that config option, I believe it's `swcMinify`.+ `swcMinify` was removed in Next.js 15 (SWC is always on) —+ confirmed in the v15 upgrade guide, checked 2026-07-19.
web-application-security untrusted input stays untrusted
String-built SQL, missing ownership checks and leaked secrets get caught at review and at write time.
- db.query(`SELECT * FROM docs WHERE id = ${req.params.id}`)+ db.query("SELECT * FROM docs WHERE id = $1 AND owner_id = $2",+ [req.params.id, req.user.id])
git the repo is shared
State gets inspected before acting; destructive commands are replaced with recoverable ones.
- git add . && git commit -m "fix" && git push --force+ git status --short --branch+ git add src/parser.ts test/parser.test.ts+ git commit -m "Handle BOM in config files"+ git push --force-with-lease # only because a rewrite was requested
typescript types that mean something
No `any` escapes, no lying assertions — illegal states become unrepresentable.
- const user = JSON.parse(raw) as any;- if (user.status == 1 || user.status == "active") { ... }+ const user = UserSchema.parse(raw);+ if (user.status === "active") { ... } // status: "active" | "suspended" — the third case can't exist
javascript modern, predictable JS
Loose equality, accidental mutation and floating promises don't survive review.
- items.sort(); // mutates, sorts numbers as strings- if (total == "0") reset();+ const sorted = [...items].sort((a, b) => a - b);+ if (total === 0) await reset();
node-js the event loop is not yours to block
Sync I/O leaves request paths; errors and shutdown get handled like production matters.
- app.get("/report", (req, res) => {- const data = fs.readFileSync(reportPath);+ app.get("/report", async (req, res, next) => {+ const data = await fs.promises.readFile(reportPath);
react state where it belongs
Derived state stops living in effects; dependencies stop being lied about.
- const [fullName, setFullName] = useState("");- useEffect(() => { setFullName(first + " " + last); }, [first]);+ const fullName = `${first} ${last}`;
nextjs server first
Data fetching moves to the server component; the client bundle stops shipping fetch waterfalls.
- "use client";- useEffect(() => { fetch("/api/posts").then(...) }, []);+ export default async function Posts() {+ const posts = await db.post.findMany({ take: 20 });+ return <PostList posts={posts} />;+ }
python idiomatic and typed
The classic traps — mutable defaults, bare excepts, float money — get caught before they ship.
- def add_item(item, cart=[]):- cart.append(item)+ def add_item(item: Item, cart: list[Item] | None = None) -> list[Item]:+ cart = cart if cart is not None else []+ cart.append(item)
sql queries the planner can love
N+1 loops become joins; `SELECT *` becomes explicit columns; migrations get rollback paths.
- for user in users: # 1 + N queries- orders = query("SELECT * FROM orders WHERE user_id = %s", user.id)+ SELECT u.id, u.email, o.id, o.total+ FROM users u JOIN orders o ON o.user_id = u.id+ WHERE o.created_at >= %s; -- one query, indexed
mongodb documents by workload
Unbounded reads get projections, limits and indexes; schemas follow the queries.
- const all = await db.collection("events").find({}).toArray();- const recent = all.filter(e => e.ts > since).slice(0, 50);+ const recent = await db.collection("events")+ .find({ ts: { $gt: since } }, { projection: { type: 1, ts: 1 } })+ .sort({ ts: -1 }).limit(50).toArray(); // uses { ts: -1 } index
redis fast stays fast
Blocking commands leave production paths; keys get TTLs and a naming scheme.
- const keys = await redis.keys("session:*"); // blocks the server+ for await (const key of redis.scanIterator({ MATCH: "session:*",+ COUNT: 100 })) { ... }+ await redis.set(`session:${id}`, data, { EX: 3600 });
powershell objects, not strings
Text parsing gives way to the object pipeline; errors become terminating and handled.
- $size = (dir $path | Out-String) -split "`n" | Select-String "Length"+ $size = (Get-ChildItem $path -File | Measure-Object Length -Sum).Sum
ui-ux-design designed, not generated
Emoji icons, template gradients and lorem ipsum are replaced with tokens, states and real content.
- <div class="card">✨ Feature 1</div>- background: linear-gradient(135deg, #667eea, #764ba2);+ <article class="card"><svg class="icon">…</svg> Invoice reminders</article>+ background: var(--surface);+ .card:focus-visible { outline: 2px solid var(--accent); }