T4 Dev Workflow

T4 Dev Workflow

Overview

The T4 team's development pipeline, built for an agent-primary repo where GitHub issues are the source of truth for what to do and its state — not a formality. Session-local todos must reconcile back to issues before the session ends. This skill covers how work flows from idea to merge, which skills fire automatically, and the tracker conventions (labels, lifecycle, bilingual bodies).

The pipeline

When planning or implementing a feature, follow this order:

1. /grill-me — stress-test the concept interview-style before committing to it.
2. /grill-with-docs — challenge the plan against existing ADRs in docs/adr/; this also lazily produces domain docs (CONTEXT.md / ADRs) when a term or decision actually resolves.
3. Survey the change sites — enumerate every place the change touches before writing the plan (below). A PRD written without this plans the change you imagined, not the one the repo needs.
4. /to-prd — turn the grilled plan into a PRD (one PRD per epic), carrying the survey as its change inventory.
5. /to-issues — break the PRD into GitHub issues with triage labels (one issue per deliverable).
6. /tdd — implement test-first (red → green → refactor).

Hard gate: PRD → issues → PR. Never open a PR without a referenced issue. A PRD becomes issues before code; code maps to an issue before a PR.

Survey the change sites before writing the plan

Most "surprise cases" aren't surprises — they're sites the plan never knew about. They surface mid-implementation, when the cheapest moment to have found them has already passed, and they arrive as scope growth (which under AFK is a 🛑 park). The survey is the step that converts them from surprises into line items.

Do it after the concept is settled (/grill-me) and before /to-prd — surveying a concept that's still moving is wasted, and planning without it is guessing.

The trigger is an action, not a phase: the first time you are about to write down what you will change. A plan, a PRD, an issue body, a comment saying "I'll edit X and Y", the first edit of a multi-file change — whichever comes first, that is the cue. Phrase it to yourself as "I am about to commit to a set of files", the same way /simplify is tied to after writing code.

Why it needed one. A step attached to a phase boundary fires only when someone happens to notice the boundary — and using-t4 already warns that boundaries are what get crossed unnoticed ("a check at task start does not discharge a later trigger"). Worked example, one session, minutes apart: on #78 the survey was skipped and the consequence arrived inside the same edit — one added clause took the injected dispatcher to 9033 B against a hard 9000 B cap. On #86 the same agent ran it first and budgeted the addition before writing it. The difference was not diligence. It was that #86's issue body handed the survey over as a section and #78's did not.

A sibling issue's change inventory is survey input. The warning that would have prevented #78 was already written down — in #86's body, read in the same session. Before surveying, check the issues adjacent to yours for an inventory someone already built; a survey that ignores one is redoing work that exists.

What to enumerate — don't stop at the obvious file:

• Every occurrence of the thing you're changing, not the first one. rg for the symbol, the string, the config key, the route, the error message. Duplicates are the classic miss: the same list, rule, or constant written in two files drifts the moment you update one — this repo's own pipeline is described in both SKILL.md and references/workflow-artifacts.md, and a change to one alone is a defect.
• Both sides of every mirror. Bilingual doc pairs (*.md / *.en.md), a doc and its diagram, a script and its copy in another delivery path, a template and the test that guards it.
• Callers, not just the definition. Who consumes this? What breaks if its shape changes?
• Tests and fixtures that assert on what you're changing — including a test whose string literals encode the old wording.
• Docs that state the current behavior. A README sentence describing what you're about to change is a change site; leaving it is how docs drift.
• Config, CI, and generated artifacts that reference the thing by name.

Output: a change inventory — a flat list of path → what changes there → how you'll verify it. Put it in the PRD (references/workflow-artifacts.md has the block) and in the issue. It becomes the implementation checklist and, later, the reviewer's map.

Say what the survey couldn't reach. "I searched rg '' across skills/ and docs/; anything reached by dynamic name construction wouldn't appear" is an honest boundary and belongs in the plan. An unstated search boundary reads as completeness you didn't verify (No verdict before evidence, below).

Cost check: the survey is minutes of rg; the alternative is finding site #4 after the PR is open, when the fix is a re-plan. It scales down — a one-file change gets a one-line survey — but it doesn't get skipped, and skipping it needs the same proof any other rule does.

The high-risk refactor protocol's "Inventory first" is this same step applied to behavior rather than files — do both when a refactor is in scope.

No verdict before evidence (don't state it as settled until it is)

A confident wrong answer is worse than an uncertain right one, because it ends the investigation. State claims in the register the evidence supports — and never upgrade a claim just because you've repeated it.

Three registers. Pick the one you've earned:

| Register | Use when | Say it like | |---|---|---| | Verified | you produced the evidence in this session | "bun test → 42 passed" · "read auth.ts:88, it returns early on null" | | Hypothesis | it's reasoning, inference, or memory | "Likely the cache key collides — unverified, would confirm by ___" | | Unknown | you don't know and haven't checked | "I don't know whether X; checking costs ___" |

A verdict word requires a named artifact. Fixed · works · passes · safe · done · the root cause is · no impact — each is a claim about the world, so each needs the command you ran, the output you saw, or the file:line you read, stated with it. Without that, downgrade the sentence to a hypothesis; don't delete the hedge to sound decisive.

These are not evidence:

• "It should work" / "by design" / "the types line up" — reasoning about code is not observing it.
• "The docs say so" — for a pinned or non-standard version, read the vendored source.
• "It worked before" / "this pattern always works" — not about this change.
• "The test exists" — existing ≠ run ≠ passing.
• Another agent said so. A subagent's or bot's report is a hypothesis until you check it (clink-subagents says the same: verify everything a subagent returns).

The laundering failure mode — the one to actually watch for: a guess stated in turn 1 gets referenced as established in turn 3, and by turn 6 it's the premise of a design decision no one can trace back to a check. A claim's register never improves by being repeated or summarized. When you carry a claim forward, carry its register with it.

Reporting is part of the rule. If you didn't run it, say you didn't — "tests not run" is a complete, acceptable sentence. Reporting a suite as green without running it is not optimism; it's a false statement about the repo. Same for partial work: name what's unfinished rather than letting "done" cover it.

Why it's load-bearing here: the records layer is an index future agents trust without re-checking (t4-engineering-records — validated-only, file:line, commit SHAs). One unverified verdict written as fact poisons it, and the cost lands on whoever inherits the repo, not on the session that saved a minute.

Skipping a rule requires proof (the burden is on the skip)

Every rule here has a cost, so there is always a locally-reasonable argument for skipping one. That argument is exactly the failure mode: skipped once with a good story, the rule stops being a rule. So the burden of proof sits on the skip, never on compliance.

The default is comply. An exemption is valid only when you can state a checkable fact about this specific change that makes the rule inapplicable — one a reviewer can verify without redoing your reasoning.

| Not a proof (judgment dressed up) | A proof (checkable fact) | |---|---| | "Small change, tests can't be affected" | "git diff --name-only is README.md only — no code path is reachable from it" | | "This is unrelated to the failing suite" | "The suite imports src/a.ts; the diff touches src/b.ts, which nothing in a imports — checked with the import graph" | | "Obviously safe" / "I'm confident" | "The function is unreferenced: rg 'fooBar\(' -g '!*.test.*' returns only its definition" | | "Running it is slow" | Never a proof. Cost is not evidence. | | "The user is in a hurry" | Never a proof. Urgency changes priority, not truth. |

If you cannot state the proof, follow the skill. Uncertainty resolves toward compliance — always, and without asking. "I'm not sure whether this needs a test" means it needs a test.

Offering the developer a choice to skip a gate is itself a skip. The rules above bind your reasoning — urgency is not a proof, uncertainty resolves toward compliance. The move that routes around both is to hand the choice over: "merge now, or run the review first — about six minutes?" The developer's "yes" is not a checkable fact about this change, so the burden of proof does not transfer by asking. It only looks like authorisation, and the skip proceeds looking approved.

Why "but they can waive it" is the wrong objection. They can. The rule is about who raises it. A developer who says "skip the review" has decided with the cost in front of them; an agent that offers "fast, or thorough?" while reporting a time estimate has framed the choice so the fast answer looks free, and has moved a gate into the developer's queue. The allowed form is: report the cost, then comply. A developer-initiated waiver remains valid; an agent-offered one does not.

This is not "never ask anything". You may still say a gate is expensive, and you may still ask when a gate is genuinely ambiguous in scope — which files a security review should cover is a real question. What you may not do is present skipping as an option you are neutral about. It is the mirror image of the over-asking failure in t4-afk: that one asks permission to do more, this one asks permission to do less. And state every judgment gate, whether or not you have an exemption to write. The exemption rule above covers a rule you argue your way out of. It does not cover one you simply never reach — and the judgment gates (/simplify, /code-review, /scrutinize, /security-review, /verify) have no hook, so skipping one used to leave no trace at all. Put the answer on the branch as a commit trailer:

T4-Gates: simplify=ran code-review=ran scrutinize=not-run security-review=n-a verify=ran

not-run is a legal answer and check-gate-ledger accepts it. The guard raises the cost of skipping a judgment gate from zero; it does not pretend to verify the reasoning, which it cannot. What it refuses is a gate you say nothing about, because an unrun gate is otherwise indistinguishable from a passed one in the only report anybody reads.

Say it where the work is reported. An exemption that lives only in your head is a violation, not an exemption: write it in the PR body / the message reporting the work, in the form rule → the checkable fact → how to verify it. This is what makes it reviewable, and what makes a wrong exemption catchable later.

Never exemptable by argument:

• Hook-enforced rules — a PR needs a referenced issue, verify must pass, dangerous git. The gate does not read prose; arguing with it means disabling it, which is the anti-pattern itself.
• Safety and trust boundaries — /security-review on anything touching auth/secrets/input trust, and the destructive-command rules. The blast radius is asymmetric: being right saves minutes, being wrong is unrecoverable.
• Anything the user has just told you to do. A direct instruction is not a rule you get to prove your way out of.

Consequence for a stated exemption that turns out wrong: it becomes a record, not a shrug — the rule that was skipped goes back on, and the wrong proof is worth a line in the post-mortem (t4-engineering-records), because a bad exemption pattern will otherwise repeat.

This meta-rule governs every "narrow exception" clause in these skills, including the one below.

Root cause before fix (applies to bugs and review findings)

Do not propose a fix, and do not edit, until you can name the root cause with evidence. The output of diagnosis is a sentence of the shape: "X fails because path/file.ts:42 does Y when Z, which I reproduced by ___." Until you can write that sentence, any fix is a guess dressed as a solution.

The order — no step skipped because the answer "looks obvious":

1. Reproduce. A failing test, a command, or an exact sequence. If you can't reproduce it, say so explicitly and treat everything after as a hypothesis, not a diagnosis.
2. Trace the actual path. Read the real code from entry point to failure — not the diff, not the file you assume is at fault. Cite file:line.
3. Falsify. State the hypothesis so it can be wrong, then try to break it. If two causes both explain the symptom, you haven't finished.
4. Then propose the fix — and say which part of the trace it addresses.

/debug-mantra (9arm) is the discipline for this; invoke it on any bug, error, stack trace, or failing test rather than working from the symptom.

Why it's a rule here: a symptom-level fix in an agent-primary repo is expensive twice — it lands, looks green, and the real cause resurfaces later with the misleading fix now in the way. It also poisons the records layer: a post-mortem written from an untraced fix is a wrong index entry, worse than none (t4-engineering-records).

Applies equally to: review findings (/scrutinize, /code-review — verify the finding against the code before acting on it, including one an agent or a bot reported), CI failures (read the log; don't re-run hoping), and performance work (measure first; a guessed bottleneck is the same error wearing a stopwatch).

The exceptions are narrow, and you say them out loud: a trivially-reversible one-liner where reproduction costs more than the change, or an emergency mitigation to stop the bleeding — in which case the mitigation is not the fix, and the root cause stays open work (ledger row + issue).

Auto-triggered skills (fire without waiting for the user)

| Trigger | Skill | Condition | |---|---|---| | About to write down what you will change — a plan, a PRD, an issue body, or the first edit of a multi-file change | change-site survey (above) | Every time. Check adjacent issues for an inventory that already exists | | Bug / error / stack trace | /debug-mantra | Start a debug session every time | | Complex debug / perf regression | /diagnose | reproduce → minimise → hypothesise → fix | | After fixing a bug | /post-mortem (see t4-engineering-records) | Record root cause + fix + validation | | After writing or changing code | /simplify | Before committing — check over-engineering | | Editing UI / frontend | /impeccable | Every time a component or CSS is touched | | Before merge / ship | /code-review + /scrutinize | Correctness + outsider perspective | | Touching auth / token / secret / any security boundary | `/securi

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xenodeve
• Source: xenodeve/xeno-skills
• License: MIT

Install and usage instructions live in the source repository linked above.