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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user