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
+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