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