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.
2026-09-14 14:36:52 -04:00
parent 2f2e3b88e8
commit 59192143c5
2 changed files with 109 additions and 16 deletions
@@ -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
@@ -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.
+2. Run the prose bar over `<slug>.md` before building anything from it. A spike
-3. Compile: `typst compile <slug>.typ <slug>.pdf`. `typst` should already be on PATH;
+   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
+   Before saving, run the prose bar (see **The prose bar** above) over the Summary and
-   the Summary and Additional Notes ONLY: puffery, superficial -ing phrases, "not just
+   Additional Notes ONLY. The pasted handoff is generated output and is never edited.
-   X but Y", vague attributions, rule-of-three padding. The pasted handoff is generated
+   Henry reads every one of these, and prose that reads as machine-generated costs the
-   output and is never edited, per the rule above. Skip unslop's "Adding soul" section
+   MR its credibility before anyone looks at the diff.
   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.
 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
+   **Run the prose bar** (see **The prose bar** above) over every field before rendering
-   PM. Run the `unslop` skill's pattern detection over the markdown before rendering it
+   it to ADF, proof and mitigation cells included. Everything here is read by the Lead
-   to ADF, skipping its "Adding soul" section — Jira fields want plain, factual, and
+   and the PM.
   specific. This does not apply to proof cells, which are references to artifacts and
   test names rather than prose.
   **Proof first.** Before filling any proof column, capture working feature proof
   yourself wherever possible: run the app (`run` skill) and screenshot the real