diff --git a/user/agents/AGENTS.md b/user/agents/AGENTS.md index c631286..ad74269 100644 --- a/user/agents/AGENTS.md +++ b/user/agents/AGENTS.md @@ -62,6 +62,40 @@ I wanted to share some of my preferences here so we can be more aligned as we wo --- +# The prose bar + +Anything a person other than me will read gets a pattern pass before it ships. MR and PR +descriptions, ticket fields, deliverable documents, reports, anything handed to a +teammate or a client. Invoke the `unslop` skill and apply its pattern detection. + +- Skip its "Adding soul" section. Opinions and deliberate mess are right for an essay and + wrong for a risk table or a status field. These want plain, factual, and specific. +- No em dashes, en dashes, semicolons, or arrow glyphs in prose. This is stricter than + unslop's own punctuation pattern, and mine wins. Grep the file before calling it done. +- Passive voice is the usual offender in technical writing, not puffery. "X was verified" + wants to be "I verified X", which is shorter and says who did it. +- Short reference cells still count. Three sentences wrapped around a filename is prose. +- Never rewrite generated output. If a tool produced a block, an audit verdict or a test + report, regenerate it rather than editing its words. +- Write it as me, in first person. Never use my name or a stand-in for it. Not "Gib + decided", not "the author", not "per the developer". If a sentence needs an actor, it + is "I". +- Never flag one of my own decisions as a deviation. Don't write that something was out + of scope, that an AC or dev review said otherwise, that an earlier story should have + caught it, or that a direction was reversed. I write the tickets, so I am allowed to + change them, and a dev review is a proposal rather than a contract. Calling it out + reads as my own AI tattling on me. It waves a red flag at a nothing burger, costs the + PM time investigating a non-issue, and leaves them thinking I did something wrong. + State what the change is and why it belongs where it is, then stop. +- If a decision feels big enough that you want to narrate it, ask me about it before + writing rather than annotating it in the document. Being aligned first is the point, + and the writing should read as though we always were. + +Files only I read are exempt: plans, scratch notes, working records. Those can name me +and record who decided what, because that history is useful. + +--- + # Merge Requests - Make sure titles follow conventions from the repo. @@ -84,5 +118,8 @@ I wanted to share some of my preferences here so we can be more aligned as we wo - Henry reviews all of my code & up until recently, would also write all the dev reviews for all the stories I completed as well. Nowadays, I write them myself & he reviews those too. - Henry likes work to be very considerate & he always prefers solutions that result in 0 downtime. - Despite the fact that Command Center does not have many users & the impact of it being down for a few minutes is small, Henry still leans on the side of solutions to problems that don't result in prod being down ever, even for just a few minutes during the build process. So our solutions should always keep that in mind. Any code that isn't considering everything & could result in a bug will probably be flagged by him, so its worthwhile to do right the first time! +- Josh - Tech Lead for the APSCA project (apsca_next) + - On APSCA, Josh is my lead instead of Henry. He reviews my code and writes the dev reviews, spikes, and proposed schemas on the APSCA stories. + - His dev reviews are detailed and often include draft code, schema, and state machines. Treat them as the starting point for a story, not as a finished spec. - Hunter Southworth - Engineering Manager / Senior Developer - Kelson - Owner of Ksense diff --git a/user/agents/skills/ticket/SKILL.md b/user/agents/skills/ticket/SKILL.md index 930d1c1..4b1dcde 100644 --- a/user/agents/skills/ticket/SKILL.md +++ b/user/agents/skills/ticket/SKILL.md @@ -108,6 +108,63 @@ rerun it, and verify the device log instead of accepting the fallback transcript - Don't check a checklist box (in `mr.md` or anywhere else) unless you actually verified it. Leave it unchecked and say why in the notes rather than guessing. +## The prose bar (anything another person reads) + +Everything this skill produces for someone else gets a pattern pass before it ships: +`mr.md`'s Summary and Additional Notes, every Jira field including the proof and +mitigation cells, and every deliverable document. Call the Skill tool with "unslop" and +apply its pattern detection. + +- **Skip unslop's "Adding soul" section.** It asks for opinions, varied rhythm, and some + mess. That is right for an essay and wrong for a mitigation cell Henry is auditing. + These want plain, factual, and specific. +- **Never edit generated output.** The pre-MR handoff pasted into `mr.md` is the audit's + own words. If it reads badly, regenerate it, don't rewrite it. +- **Proof cells are prose too.** A cell that wraps three sentences around a filename is + writing, not a citation, and it picks up passive voice and jargon like any other + paragraph. Real examples caught this way: "affordance" for button, "vacuously" for + "for the wrong reason", "the test was confirmed able to fail" for "I emptied the + legacy render and confirmed the test fails". +- **Passive voice is the usual offender here,** not puffery. Technical writing drifts + into "X was verified" when "I verified X" is shorter and says who did it. + +### Write as Gabriel, and never flag his own decisions + +Everything that ships under his name is written **as him**, in first person. Never write +his name or any stand-in for it. Not "Gib decided", not "the author", not "per the +developer". When a sentence needs an actor, it is "I". + +**Never frame one of his decisions as a deviation.** Do not write that something "was not +in this story's scope", that an AC or dev review said otherwise, that an earlier story +"should have caught it", or that a direction was "reversed". State what the change is and +why it belongs where it is, then stop. + +He writes the tickets himself, so he is entitled to change them, and a dev review is a +proposal rather than a contract. Calling the change out reads as his own AI tattling on +him. It waves a red flag at a nothing burger, costs the PM time investigating a +non-issue, and leaves them assuming he did something wrong. The real story is normally +mundane and good: the better component already existed and cost almost nothing to use. + +Compare, on KACP-23058: + +> Bad: "This was not in this story's scope. KACP-23059 shipped that page still on the +> legacy tables, and Gib reversed the reuse-legacy direction on 2026-09-02." +> +> Good: "Both detail pages now share one set of grid components instead of two divergent +> implementations, so the move ships with the components it shares." + +Same information, no flag attached. **If a decision feels big enough that you want to +narrate it, that is the signal to ask him about it before writing, not to annotate it in +the document.** Being aligned first is the point, and the writing should read as though +you always were. + +This governs `mr.md`, `customfield_10260` and `10261`, every other Jira field, and PM +deliverables. It does not govern files only he reads. `plan.md`, `bugs.md`, audits and +working notes can name him and record who decided what, because that history is useful. + +The House style punctuation rule above is the stricter one where the two overlap. Keep +it. Personal working files (`plan.md`, `ticket.md`) are exempt, nobody else reads them. + ## Verification tools available The goal isn't "a plausible-sounding plan" or "code that compiles" — it's a plan and @@ -226,15 +283,19 @@ method for producing accurate screenshots, not part of the deliverable's story. Process, per deliverable: 1. Write `.md`. -2. Write `.typ` from it, per the styling notes above. -3. Compile: `typst compile .typ .pdf`. `typst` should already be on PATH; +2. Run the prose bar over `.md` before building anything from it. A spike + deliverable is the most prose-heavy thing this skill produces and it goes straight to + Conrad, who is skeptical of AI. Fixing it here means fixing it once, rather than in + the markdown and again in the Typst. +3. Write `.typ` from it, per the styling notes above. +4. Compile: `typst compile .typ .pdf`. `typst` should already be on PATH; if it isn't, tell the user rather than silently skipping the PDF. -4. Actually look at the compiled PDF using the Read tool (it reads PDFs directly, page +5. Actually look at the compiled PDF using the Read tool (it reads PDFs directly, page by page for longer documents). Check every page for real layout problems: text or a table overflowing a page, an awkward page break splitting a table or diagram, cramped or excessive spacing, a diagram that rendered wrong. A successful compile only means valid Typst, not that it looks right — actually look. -5. If anything looks wrong, fix `.typ` and go back to step 3. Repeat until the +6. If anything looks wrong, fix `.typ` and go back to step 4. Repeat until the PDF genuinely looks right, not just until it compiles without erroring. If `.claude/docs/` is tracked by git in this repo (check with @@ -756,13 +817,10 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved content. A reviewer should be able to read the whole file in about a minute; if it has grown past roughly 120 lines including the handoff, it has drifted. - Before saving, call the Skill tool with "unslop" and apply its pattern detection to - the Summary and Additional Notes ONLY: puffery, superficial -ing phrases, "not just - X but Y", vague attributions, rule-of-three padding. The pasted handoff is generated - output and is never edited, per the rule above. Skip unslop's "Adding soul" section - too — an MR description wants plain and factual, not voice. Henry reads every one of - these, and prose that reads as machine-generated costs the MR its credibility before - anyone looks at the diff. + Before saving, run the prose bar (see **The prose bar** above) over the Summary and + Additional Notes ONLY. The pasted handoff is generated output and is never edited. + Henry reads every one of these, and prose that reads as machine-generated costs the + MR its credibility before anyone looks at the diff. 9. Fill the Jira ticket fields directly, by issue type. Rich text fields are ADF: render markdown with `python3 ~/.agents/skills/review-ticket/scripts/review2adf.py render ` and PUT via `{"fields": {...}}` to `/rest/api/3/issue/`. @@ -771,11 +829,9 @@ Entered only when the user has confirmed (per Phase 0) that the plan is approved field-to-type map below is verified against the project's edit screens, don't PUT a field to a type that doesn't carry it. - **Same prose bar as `mr.md`.** Every field authored here is read by the Lead and the - PM. Run the `unslop` skill's pattern detection over the markdown before rendering it - to ADF, skipping its "Adding soul" section — Jira fields want plain, factual, and - specific. This does not apply to proof cells, which are references to artifacts and - test names rather than prose. + **Run the prose bar** (see **The prose bar** above) over every field before rendering + it to ADF, proof and mitigation cells included. Everything here is read by the Lead + and the PM. **Proof first.** Before filling any proof column, capture working feature proof yourself wherever possible: run the app (`run` skill) and screenshot the real