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