1---
2name: prep
3description: Examine one ticket, work out the fix, and write the plan back onto the ticket — description, risk, effort, priority — without implementing anything. Use when the user types /prep, or says "look at this ticket", "plan this ticket", "propose a fix for LAB-123", "scope this ticket", "groom this ticket", "make this ticket ready". Portable across Claude Code, Codex, and any agent that reads skills.
4---
5
6# prep — propose the fix, update the ticket, build nothing
7
8Input: one ticket (ID, URL, or "this ticket" from the conversation). Output: the
9same ticket, rewritten so someone else — a person or an agent — can pick it up
10and build it without asking a question.
11
12**Hard boundary: plan only.** No code edits, no branches, no commits, no PRs, no
13migrations, no deploys. Reading code, running read-only commands, and reproducing
14a bug are fine. If the fix turns out to be a one-liner, still don't make it —
15write it into the ticket.
16
17## Tracker access
18
19Default tracker is Linear. Use whichever is available, in this order:
20
211. The Linear MCP server, if one is connected to this agent.
222. The Linear GraphQL API with a key from `LINEAR_API_KEY` or the machine's
23 secret store (on macOS: `security find-generic-password -s linear-api-key -w`).
24 Never print the key.
25
26For a GitHub issue use `gh issue view` / `gh issue edit` and map the fields
27below onto labels. No tracker access → stop and say so; don't write the plan
28into a local file instead.
29
30## Steps
31
32### 0. Move a triage ticket to Todo
33
34Before investigation or planning, fetch the ticket and confirm its identity,
35team and current status. If it is in Triage, move it to the team's actual
36to-do status (soclever: `Todo`) and read back to verify. Change only the status
37in this update. If it is not in Triage, leave its status unchanged. Prep is
38planning only, so do not apply a general rule that moves picked-up tickets to
39In Progress. Do not ask for confirmation; report a failed update honestly.
40
41### 1. Read the ticket — all of it
42
43Fetch the ticket by ID and confirm it's the right one (title matches what the
44user meant). Read the description, every comment, attachments and images,
45linked and parent/sub tickets, and the current project, estimate, priority,
46status and labels. Note what the reporter actually asked for versus what the
47title says.
48
49### 2. Understand it — research only as far as needed
50
51Find the cause or the shape of the work, at the depth the ticket needs:
52
53- **Clear and small** (copy, a known one-file change): locate the spot in the
54 code and move on. No research.
55- **Bug**: find the code path, and reproduce it or pin the cause from the code.
56 State whether the cause is *confirmed* (reproduced / read in code) or
57 *suspected*.
58- **Feature or unclear ask**: read the surrounding code and how similar things
59 are already done in the repo. Search open and recently closed tickets for
60 overlap.
61- **External unknown** (a vendor API, a library behaviour, a legal or pricing
62 fact): only then go to the web, primary sources first.
63
64Stop researching as soon as you can name the fix and its risk. If the ticket
65names no repo, work out which one from the team/project before reading code.
66
67### 3. Decide the fix
68
69One recommended approach, concrete enough to build from: what changes, where,
70and in what order. Mention an alternative only if it's a real contender, in one
71line with why it lost. If two approaches differ in a way only the owner can
72judge (product behaviour, money, scope), don't pick silently — see "Open
73questions" below.
74
75### 4. Rewrite the description
76
77Replace the description with the structure below. Keep everything true from the
78original — the reporter's words, links, screenshots — under **Source**; never
79drop information. Plain language first; file paths and identifiers are welcome
80in "Proposed fix" where a builder needs them.
81
82```markdown
83## What
84One or two sentences: the problem or the ask, as the user experiences it.
85
86## Why
87Who it affects and what it costs to leave it.
88
89## Where
90Product area / screen, plus repo and the main files involved.
91
92## Cause
93(bugs only) What's actually wrong — marked confirmed or suspected.
94
95## Proposed fix
96Numbered steps a builder can follow. Name files/functions. Include the test
97that should exist when it's done.
98
99## Risk
100Level: Low / Medium / High — rate the planned work and say why.
101- What could break, and who would notice
102- Blast radius: one screen / one app / shared code / data / money / outbound messages
103- Reversible? How to roll back
104- What must be checked before shipping
105- Conditional escalation, only if needed: what finding or scope change raises the risk
106
107## Done when
108Checkable acceptance criteria.
109
110## Open questions
111Only if any. Each with a recommended answer.
112
113## Source
114Who asked, where, when; original wording; links.
115```
116
117Drop a section that genuinely doesn't apply (no "Cause" on a feature, no "Open
118questions" when there are none). Never drop **Risk**.
119
120**Rate the concrete work, not the topic.** Risk describes the proposed
121implementation or verification, not the act of writing this plan, the severity
122of a possible bug, or the worst fix an investigation might uncover. A ticket
123about permissions or payments is not automatically High risk. Keep priority
124(the impact of leaving the problem) separate from change risk.
125
126**Risk level guide** (shared policy: `ops/linear-ticket-risk.md` in the
127meirlabs homebase). Low: read-only investigation, tests using isolated
128synthetic data, or an isolated, easily reverted change with no material effect
129on live data. Medium: a self-contained change that one screen check or a
130covering test proves. High: touches shared pieces many pages use (layout, nav,
131chat engine, sign-in), migrations or backfills, payments/points/caps or anything
132sent to users, shared AI prompts, or needs several screens, devices or accounts
133to verify. Very high: consequential and hard to undo — authorization changes for
134everyone, live money movement, destructive live-data migrations, real sends at
135scale. Judge actual side effects: a test that changes production records or
136sends real messages is not Low merely because it is called a test.
137
138For verification-first work, rate the verification being proposed. If a finding
139would require a riskier fix, state that separately with the concrete trigger
140and re-scope/re-rate before implementing it. For example: "Low for ownership
141regression tests with synthetic accounts; High if a failure requires changing
142authorization checks." Do not inflate the main rating with a hypothetical
143repair, or describe an unverified breach as a confirmed defect.
144
145### 5. Set the fields
146
147- **Title** — fix it if it's vague or wrong: 2–6 plain words, verb-led, no codes.
148 The one allowed prefix is the risk emoji below; keep it in sync, never double it.
149- **Risk flag** — mirror the planned rating: High → workspace label `Risk: High`
150 + title prefix `🔔 `; Very high → `Risk: Very high` + `🧨 `; Low/Medium →
151 neither (remove a stale one). Exactly one label+prefix or none; touch no
152 other labels.
153- **Effort** — the tracker's estimate field, on the team's own scale (read the
154 team settings; don't assume). Base it on the proposed fix, including tests
155 and verification. Use only that relative effort scale; do not translate it
156 into hours, days, weeks or a completion date. Do not add duration estimates
157 to the ticket description, comments or user reply. Explain the scope and
158 uncertainty behind the effort instead.
159- **Priority** — Urgent / High / Medium / Low from impact (who's affected, how
160 badly, how soon). Never leave "No priority". If you change an existing
161 priority, say why in the comment.
162- **Project** — set if missing; best-fitting existing project in the team.
163- **Labels** — fix if wrong or missing (bug / feature / etc.).
164- **Status** — keep the status established in step 0: Triage becomes the
165 team's to-do status; otherwise leave it unchanged. Don't move it to
166 in-progress; nobody is building. Don't change the assignee.
167
168If the ticket duplicates another, don't plan it twice: carry any new detail
169into the keeper, mark this one Duplicate, and report that instead.
170
171### 6. Comment — only when it adds something
172
173Add one comment when any of these is true; otherwise none:
174
175- You changed priority, estimate or title — say from what to what, and why.
176- There are open questions the owner must answer before building.
177- Research turned up something that doesn't belong in the description (a dead
178 end worth not repeating, a related ticket, evidence of the repro).
179
180Keep it short. Don't paste the plan again.
181
182### 7. Read back and verify
183
184Re-fetch the ticket and check that the description, title, estimate, priority,
185project, status, labels and risk flag (label and prefix agree) actually stuck.
186Fix anything that didn't.
187
188## Reply to the user
189
190Short, no recap of the ticket body:
191
192```
193LAB-123 updated — <title>
194- fix: <one line>
195- effort: <estimate> · priority: <priority> · risk: <level>
196- open question: <only if any>
197```
198
199## Rules
200
2011. **Never implement.** The deliverable is the ticket.
2022. **Never lose information.** Rewriting the description keeps the original
203 facts and links.
2043. **Honest confidence.** A suspected cause is labelled suspected; an estimate
205 resting on an unknown says so in Risk.
2064. **One ticket per run** unless the user gives a list — then run the steps per
207 ticket and reply with one block per ticket.
2085. **Split, don't bloat.** If the fix is really two independent pieces of work,
209 propose the split in "Open questions" (or the comment) rather than creating
210 new tickets unasked.
211