Docs: Add the prose bar and record Josh as the APSCA lead

Anything a person other than me reads now gets an unslop pattern pass
before it ships: MR descriptions, ticket fields, deliverables. The rules
that matter most are the ones a generic pass misses. Write as me in first
person, never name me or use a stand-in, and never flag one of my own
decisions as a deviation, because that reads as my own AI tattling on me
and costs the PM time investigating a non-issue.

Punctuation is stricter than unslop's own pattern: no em dashes, en
dashes, semicolons or arrow glyphs. Generated output is never rewritten,
only regenerated.

Also records Josh as the tech lead on apsca_next, whose dev reviews carry
draft code and schema and are a starting point rather than a finished spec.
This commit is contained in:
Gabriel Brown
2026-09-14 14:36:52 -04:00
parent 2f2e3b88e8
commit 59192143c5
2 changed files with 109 additions and 16 deletions
+37
View File
@@ -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
+72 -16
View File
@@ -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 `<slug>.md`.
2. Write `<slug>.typ` from it, per the styling notes above.
3. Compile: `typst compile <slug>.typ <slug>.pdf`. `typst` should already be on PATH;
2. Run the prose bar over `<slug>.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 `<slug>.typ` from it, per the styling notes above.
4. Compile: `typst compile <slug>.typ <slug>.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 `<slug>.typ` and go back to step 3. Repeat until the
6. If anything looks wrong, fix `<slug>.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 <file.md>` and PUT via `{"fields": {...}}` to `/rest/api/3/issue/<KEY>`.
@@ -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