AGENT SKILL

work-on-ticket

Work a rasp ticket end to end — read the Linear issue, check deps, move it to In Progress, branch, implement, verify every acceptance criterion, open a PR, and close the issue out. Use this whenever a milestone ID appears (M0-02, M1-09, M5-04, P2-SUBAGENT), or the user says "next ticket", "pick up the CI one", "start M3-04", "implement the workspace confinement", or otherwise asks for work that maps to a milestone item — even when they never say the word "ticket". Also use when finishing, reviewing, or closing one out.

License 许可
MIT
所属仓库
theocod3s/rasp
最近更新
2026-09-04
Stars
★ 0
Forks
0

01 前言 Front Matter

name
work-on-ticket
description
Work a rasp ticket end to end — read the Linear issue, check deps, move it to In Progress, branch, implement, verify every acceptance criterion, open a PR, and close the issue out. Use this whenever a milestone ID appears (M0-02, M1-09, M5-04, P2-SUBAGENT), or the user says "next ticket", "pick up the CI one", "start M3-04", "implement the workspace confinement", or otherwise asks for work that maps to a milestone item — even when they never say the word "ticket". Also use when finishing, reviewing, or closing one out.

03 SKILL.md 正文

Working a rasp ticket

~91 MVP items. Doing them consistently matters more than doing any one cleverly. This is the sequence, and the reasoning behind the parts that are easy to skip.

1. Read the ticket, and its spec

Tickets live in Linear and nowhere else — project Rasp, one milestone per M0–M5 plus one per future phase. Find one by its ID: search the project for M0-02 and take the exact title match (M0-02 · CI); fuzzy matches rank below it.

Every ticket names a spec anchor (design §13, prd §6.6). Read that section before writing anything: the ticket is a decomposition, not the requirement, and where the two disagree the spec wins.

Check Depends on. They live in the description as prose, not as Linear blocking relations, so nothing enforces them and nothing will stop you starting a ticket whose dependency is unmerged. If one is, say so and stop rather than working around it.

Don't invent scope. If something looks missing it is usually deliberate — check docs/scope.md's "deliberately excluded" before adding it. If it's a real gap, raise it; don't silently fill it. VISION.md's closing accept/resist tests are the acceptance policy: a change that passes the ticket but fails them is a conflict to raise, not to ship.

2. Claim it, then branch

Move the issue to In Progress before writing anything, even for a ticket that will take ten minutes. Linear is the only record of where the work stands, so a ticket in Todo while a branch exists is the same failure as one left In Progress after merge (§6): the next session reads the board and gets the wrong answer.

Branch rasp/<id-lowercased>-<slug> — rasp/m0-02-ci — from an up-to-date main.

3. Implement

Read AGENTS.md first if you haven't this session. It carries the invariants that are cheapest to break by accident, and violating one is far more expensive than the ticket is worth.

Comments: follow .agents/skills/comment-density/SKILL.md while writing, not after. The habit it stops is invisible from inside — a review round asks "why?", the answer is appended to the comment, nothing is ever taken back out, every round is an improvement and the file still ends up a third prose. M0-06 shipped internal/llm at 45% comment lines that way. The default is bare code. An exported identifier owes go doc one sentence; an unexported one owes nothing; no function gets a comment for merely existing. Past that, a comment earns its place only by recording what the code cannot say — why a rule exists, which provider wire shape forced it, why it is deliberately not stricter — and says it in a sentence or two, not a paragraph. Cut what restates the identifier, and cut what the error string three lines below already says in full sentences.

4. Verify every acceptance criterion, one at a time

The criteria are the definition of done, written so someone who didn't do the work can check them. Go through them individually rather than concluding "it works".

A check you have only seen pass is not evidence. If the ticket adds a test, a lint, a CI gate — anything whose job is to fail — break the thing it guards on purpose and watch it fail, then restore. This is the single highest-value habit in this repo: it is how all three of the bugs behind AGENTS.md's "a check that cannot run must fail, not pass" were caught, and none of them was visible from a green run.

The trap inside that habit: a break that stops the package compiling proves nothing. M0-04 replaced the string-aware JSONC comment stripper with a naive one and the suite went red — but red from the build, so no test ran and none was shown to catch anything. if false { does it too, whenever it leaves a variable or an import unused. If your break produces a build error, it is the compiler that caught you, not the check.

And assert the right failure, not just a failure. M0-05's timeout test checked that some error came back. A later fix broke working credential helpers by returning a different error a second sooner, and the test stayed green — passing precisely when the thing it guarded was being destroyed. err != nil is the assertion most likely to survive its own subject.

Mutate what a test rests on, not only what it asserts. The check being weak is the failure you look for; the test being incapable of failing is the one you find. M0-07 shipped three at once — defer stream.Close() could be deleted with the whole suite green, a usage check read the same pointer before and after the drain, and a third pinned the SDK's JSON key order, which would go quiet the day that order changed. All three read fine, and all three surfaced only when something they silently rested on was broken. So mutate the setup line, the helper and the literal nothing asserts on — and make a helper that finds nothing to examine say so, because examining nothing is the quietest pass there is.

Once there is more than a handful, script it: apply one mutation, run the tests, restore, print caught/not-caught per case. M0-04 ran twenty-four that way in under a minute, which is the difference between doing this for the two obvious guards and doing it for all of them. Restore by writing back the bytes you replaced — never git checkout -- ., which resets the whole tree to HEAD and takes every uncommitted change with it. It did.

A not-caught result has three causes and only one is the check's fault. The check may be weak; the test may never reach the line you mutated; or the -run pattern may match no test at all, which exits 0 and reads exactly like a pass. M0-06 hit the second (a guard reached only after the stream had already been abandoned) and the third (a subtest name with an apostrophe in it). Make the harness shout when nothing ran, and confirm the line runs, before touching the check.

Then just ci — fmt-check, vet, build, test, race. Run it before pushing, not after.

5. Open the PR

Write the description for an engineering director. Someone two levels out from the code should read it and know what shipped and why it matters — so lead with what the PR does, in plain language, then only what the reviewer genuinely needs: a judgement call and its alternative, a risk, a piece deliberately left out. Don't list the acceptance criteria; they live in the ticket, and copying them turns the description into a form nobody reads.

Keep it short enough that the reader reaches the diff. M0-04's body ran past a thousand words re-arguing reasoning already in the commits and the code — and a description nobody finishes fails at its only job. If a decision needs a paragraph to defend, that paragraph belongs in the code, where the next reader is actually standing.

Don't merge your own PR unmarked. Run /code-review, and treat its findings as claims to check rather than facts — it has a real false-positive rate, and rejecting a wrong finding with reasoning is as valuable as fixing a right one.

Then remember the fixes are code nobody has reviewed, so any pass whose fixes changed behaviour earns another. M0-05 took five passes for 17 findings, and pass 3's fix caused pass 4's worst bug: cmd.WaitDelay starts its timer when the child exits, so the fix for a helper that hung became a failure for every helper that worked.

Stop at the first pass that finds no defect in behaviour — fix its wording findings, but don't re-run for them. Waiting instead for a pass that finds nothing, or that reports its own last findings already fixed, does not terminate: M0-06a ran nine passes and never got one, because naming and phrasing findings do not run out. Its substance stopped moving at pass three.

Record anything the work settled that outlives it. If the ticket fixed a rule new code could quietly reverse — one every adapter must follow, a format nobody may change, a tempting fix that is wrong — add it to docs/decisions.md in this PR, while the reasoning is still in your head.

The bar is high on purpose, and it is not "what did I choose". It is: would someone who never saw this work re-derive it, or undo it believing they were fixing something? Three things fail that bar. What is still open belongs in the Linear issue that will settle it, not here. What shapes one file belongs in that file, where the reader is standing. What a document already says stays there — design.md is the primary reference and this does not restate it. Most tickets add nothing, and that is the expected outcome.

6. Merge and close out

Squash-merge, with a message you wrote rather than the one GitHub concatenates — see the rule in AGENTS.md. Then move the issue to Done in the same pass — the other half of §2's rule, and an issue left In Progress after merge misleads exactly as much as one never started.

If the ticket's shape changed while you worked it, edit the issue description to match what was actually built. A ticket that no longer describes its own outcome is worse than no ticket, because it still reads as authoritative.

7. Report back

Once the PR is merged and the issue is Done, write the closing summary for a CTO: someone who knows the project but has not seen this work, will not open the diff, and cannot be assumed to know what any identifier or section number refers to. So expand a term the first time it appears, and describe every change by what it now does before naming what it touched.

  • One or two sentences on what the work delivers, in plain language.
  • Then file by file, what changed in each — a sentence or two per file, its new behaviour and the reason for it, not a restatement of the diff.
  • Anything that genuinely needs a decision.

Short, not thin: no reasoning trail, no verification narrative, no caveats gathered along the way — detail earns its place before the work, or when something failed or went differently than asked. But short is not the same as understandable: a wall of identifiers standing in for sentences is a report that has to be decoded, which is a report not delivered.

This is the only place the closing summary is specified. AGENTS.md carried a second version until the two asked for opposite reports; don't start a third.


Revising this skill

This file should get better as tickets teach us things. After closing one out, ask: did anything here mislead me, go missing, or have to be re-derived? If so, amend it in the ticket's own PR, so the change is reviewed alongside the work that motivated it.

Two things keep this from rotting into a changelog:

Only record what changes what someone does next time. A rule that applies to one ticket is a note in that PR, not a line here. If you can't name a future ticket it would have helped, leave it out.

Prune as you add. Target ~150 lines. When you add something, look for what has stopped earning its place — a step now enforced by a test, advice that turned out situational, a caveat about a milestone long since shipped. A skill nobody reads to the end fails exactly the way a 2,100-line design document does, which is why this file exists at all.

Say why, not just what. "Verify checks by breaking them" is forgettable; the fmt-check example is not.

04 同仓库更多 Skills