acstack 0.50.4 → 0.51.0

package/skills/visual-docs/SKILL.md

@@ -1,246 +1,80 @@
 ---
 name: visual-docs
-description: "Write or restructure documentation that leads with a diagram and derives its structure from it. Use whenever the user asks for docs, a README, an architecture or workflow write-up, an explainer, or says existing docs are hard to follow, confusing, or a wall of text – and whenever you are about to write more than two paragraphs explaining how something works. Applies the Minto pyramid: answer first, then support."
+description: Structure documentation around the reader's questions and the relationships being explained. Use for documentation, architecture, workflows, and explanations that need more than a short direct answer. Add diagrams when they clarify those relationships.
 ---
 
-# visual-docs
-
-*A reader should see the system's shape from one diagram. They then find every detail in a section that maps to a part of it.*
-
-This skill makes a doc lead with a diagram, then derive its sections from that diagram.
-
-- **Most technical docs explain in reading order rather than importance order**
-    - The reader builds the picture themselves and learns what mattered last
-- **One diagram carries the whole shape**
-- **Every section maps to a part of that diagram**
-- **The prose rules live in the `writing` skill**
-- This skill owns shape alone
-
-This skill owns document shape. Prose follows the `writing` skill.
-
-```mermaid
-flowchart TD
-    A["Establish the shape<br/>(read code, not existing docs)"] --> B["Draw the lead diagram<br/>(section 4)"]
-    B --> C["Derive sections from nodes<br/>(section 1)"]
-    C --> D["Write the opening<br/>(section 2.1)"]
-    D --> E["Fill sections in bullets<br/>(sections 2.2 and 3)"]
-    E --> F{"Siblings MECE?<br/>(section 2.3)"}
-    F -->|no| C
-    F -->|yes| G["Check every node has a section<br/>(section 6)"]
-    G --> H["Verify the diagram renders"]
-```
-
-| Step in the diagram      | Detail          |
-| ------------------------ | --------------- |
-| Derive sections          | section 1       |
-| Opening, vertical, MECE  | section 2       |
-| Bullets carry the body   | section 3       |
-| Draw and label           | section 4       |
-| Headings and duplication | section 5       |
-| Full order of operations | section 6       |
-| What to avoid            | section 7       |
-
-## 1. The rule that makes this work
-
-*The diagram is the table of contents. If a section has no home in the diagram, one of the two is wrong.*
-
-Every numbered section maps to an element of the lead diagram, and a section heading reuses the diagram's node label verbatim. This is mechanical, not stylistic:
-
-- A box showing something **happening**, with no section, means the doc is incomplete
-- A section covering no part of the diagram either belongs in another doc, or the
-  diagram is missing something
-
-- Renaming a box renames its section, and the reverse
-
-Three exemptions, and only these three.
-
-- **Start and end boxes** – a box for what comes in, or what remains after, is not a step and needs no section
-    - In a workflow diagram, the incoming request and the final stored output are both this
-- **Two boxes, one command** – two boxes are sometimes worth drawing separately because they are two ideas, though one command does both
-    - Give them one section and name both in the heading
-        - The reader can tell it covers both
-- **Sections about the document** – a section on what this doc leaves out, or what is about to change, is housekeeping for the reader
-    - It describes the document rather than the system
-        - No box should exist for it
-
-**Start and end boxes.** A box for what comes in, or what remains after, is not
-a step and needs no section. In a workflow diagram, the
-incoming request and the final stored output are both this.
-
-**Two boxes, one command.** Sometimes two boxes are worth drawing separately
-because they are two ideas, but one command does both. Give them one section and
-name both in the heading, so the reader can tell it covers both.
-
-**Sections about the document.** A section on what this doc leaves out, or what is
-about to change, is housekeeping for the reader. It describes the document, not the
-system, so no box should exist for it.
-
-- Anything else without a match is a defect in one of the two
-- Do not add a section to justify a node, or a node to justify a section
-- End the lead diagram with a mapping table when the doc has more than four sections
-    - The table lets the reader jump from a box to its detail
-
-End the lead diagram with a mapping table when the doc has more than four sections. It lets the reader jump from a box to its detail.
-
-## 2. Minto pyramid
-
-*Answer first. Every level summarises the level below it. Siblings are the same kind of thing, and they are complete.*
-
-### 2.1. Open with one sentence, then bullets
-
-*Say what the thing is and who it is for in one sentence. Put everything else in bullets under it.*
-
-The opening is never a paragraph. A reader meeting the doc for the first time scans it. A four-sentence block of setup is the part they skip.
-
-- **Sentence one names the thing and what it does**, in words a developer who has never seen this repo already knows
-- **Bullets under it carry the rest**: what problem it solves, what it costs, what it does not do
-- **A bullet that needs context gets a sub-bullet**, never a second sentence
-
-| Beat | Where it goes |
-| ---- | ------------- |
-| **What this is** | the opening sentence |
-| **What it solves** | the first bullet |
-| **What it costs, or does not do** | a later bullet |
-| **Where to go next** | the contents table, or the last bullet |
-
-Two rules keep the opening honest.
-
-- The answer goes first, never at the end
-- A reader who stops after the opening sentence and the first bullet must still leave with the conclusion
-
-### 2.2. The vertical rule
-
-*A heading's takeaway must summarise everything under it, and nothing else.*
-
-- Put one italic line under every H2 and H3, stating the section's point
-- Test it by deleting the section body
-- It was a label rather than a summary, if the takeaway no longer tells the reader what they need
-
-### 2.3. The horizontal rule
-
-*Siblings must be the same kind of thing, mutually exclusive, and collectively cover the parent. This binds every bullet, not only every section.*
-
-Apples-to-apples applies at every level. Under one heading, at one indent, every bullet answers the same question. A bullet about what the tool does cannot sit beside a bullet about where to install it.
-
-- Write: three bullets, each naming one failure mode the tool solves
-- Not: two bullets naming a failure mode, a third naming the install command
-
-Three failures to check for:
-
-- **Mixed kinds** – three sections about components and a fourth about history. The fourth belongs elsewhere
-- **Overlap** – two sections that both explain the same mechanism from different angles. Merge them
-- **Gaps** – the parent's takeaway claims something the children do not cover
-
-Then order the siblings deliberately, and say which order you used if it is not obvious:
-
-| Order         | Use when                                       |
-| ------------- | ---------------------------------------------- |
-| **Time**      | the thing is a sequence – a pipeline, a request |
-| **Structure** | the thing has parts – components, modules       |
-| **Degree**    | the parts differ by importance or size          |
-
-## 3. Bullets carry the body
-
-*A reader scans a list and skips a paragraph. Put the body in bullets, and keep prose for the opening.*
-
-Ten rules govern a bullet. Each one is a way to write.
-
-- **Bullets carry 90% or more of the body** – prose survives in the opening sentence and in a section takeaway, and nowhere else
-- **One sentence per bullet** – split "X and also Y" into two siblings, or nest one under the other
-- **No bullet ends in a period**, however long it runs – a question mark or an exclamation mark is fine
-- **A sub-bullet carries what its parent cannot hold** – it argues for the parent, adds the detail the point needs, or lists the questions under it
-- **Every level reads top-down** – a reader who stops at any level still leaves with the point
-- **Nest as far as the argument needs, then stop** – depth costs nothing while every level adds a point
-- **Cut a level that restates its parent** – that one costs the reader everything
-- **Indent a markdown file by four spaces per level** – a `- ` marker opens its content at column 2
-    - Eight spaces sit four past that column
-        - CommonMark renders the child as a code block
-- **Use parallel grammar across siblings** – the same kind of thing then reads as the same kind of thing
-- **Cut any bullet that narrates, softens or restates**
-
-Three shapes stay prose, because a bullet breaks them.
-
-| Shape | Why it stays prose |
-| ----- | ------------------ |
-| the opening sentence | one sentence naming the thing, by section 2.1 |
-| a section takeaway | one italic line under the heading, by section 2.2 |
-| a numbered procedure | a step is a step, and rule 1 of the `writing` skill caps it at 20 words |
-
-Pick a table over a bullet list wherever every item answers the same two or three questions. Pick a bullet list wherever the items differ in shape.
-
-The output style `ac-writing-style` applies these same ten rules to a chat reply. This section is where the rules live, and that file is one reader of them.
-
-Indent every nested bullet four spaces per level, in a terminal reply and in a file alike. Claude Code and GitHub both read a wider indent as run-on text under the parent, not as a list.
-
-## 4. Diagrams
-
-*One diagram carries the doc. Others are local aids and are optional.*
-
-### 4.1. Pick the type from the question the diagram answers
-
-| Question                        | Diagram              |
-| ------------------------------- | -------------------- |
-| What talks to what?             | `flowchart`           |
-| In what order, and who waits?   | `sequenceDiagram`     |
-| What states can this be in?     | `stateDiagram-v2`     |
-| What decides which path?        | `flowchart` with gates |
-| What is stored, and how related? | `erDiagram`           |
-
-- A workflow with decision points is a flowchart, and not a sequence diagram
-- A handoff between agents or services over time is a sequence diagram, and not a flowchart
-- Choosing wrong is the most common reason a diagram fails to explain anything
-
-### 4.2. Label for a reader who does not know the codebase
-
-*Human-readable name first, technical name underneath.*
+# Visual docs
+
+Choose the smallest document structure that makes the answer and its supporting relationships clear.
+
+Read `../writing/SKILL.md`, including its shared-standard loading instructions, before drafting if you have not read it this session.
+This skill applies that standard to document structure; it does not maintain a second communication standard.
+
+## Establish what the reader needs
+
+- Identify the reader's question and the answer the document must support
+- Check the relevant code, configuration, and entry points before describing current behavior
+- Separate current behavior from proposals and decision history
+- Choose the relationships that explain the answer
+    - A workflow needs sequence, decisions, and failure paths
+    - A component explanation needs responsibilities, interfaces, and dependencies
+    - A comparison needs consistent criteria across options
+
+## Choose structure from those relationships
+
+- Start with the answer and enough orientation to make the answer meaningful
+- Group supporting detail under the questions it answers
+- Make each heading summarize its section
+    - Add a takeaway only when it provides information the heading cannot carry clearly
+    - Use numbered headings when readers need stable, visible cross-references
+- Reuse names across the overview, diagrams, and detailed sections
+    - If a diagram says "SessionStart hook", identify its source as `hooks/session-start.sh` in the detail
+    - Link overview elements to sections when readers need help finding the detail
+- Keep crosscutting relationships visible
+    - A dependency shared by two components belongs in a dependency explanation, not under an invented owner
+    - Section order can follow a reader's questions without mirroring the directory tree
+- Stop adding structure when another heading, list level, or diagram would repeat an existing point
+
+## Use diagrams when they explain more clearly than prose
+
+A diagram is useful when a reader must track several relationships at once.
+A short answer or straightforward explanation needs no diagram.
+
+| Reader's question | Useful diagram |
+| --- | --- |
+| What depends on what? | Flowchart with named dependency edges |
+| Who calls whom, and in what order? | Sequence diagram |
+| What states and transitions exist? | State diagram |
+| What determines the next step? | Flowchart with decisions |
+| What data is related? | Entity relationship diagram |
+
+- Place an overview diagram early when it gives readers the picture needed for the detail
+- Show dependencies and interactions as edges; use containment only for genuine part-whole relationships
+- Label elements in plain language and connect them to technical names
+- Label edges when their meaning is not obvious
+- Include relevant failure paths and conditions
+- Split a diagram when readers cannot follow it at a glance
+    - A node count can prompt review, but it does not determine whether the diagram is clear
+- Carry meaning in labels, not color alone
+
+For example, two callers can share a module without containing each other:
 
 ```mermaid
 flowchart LR
-    A["Write failing tests<br/>(test-writer)"] --> B["Make them pass<br/>(task-executor)"]
-    B --> C["Verify<br/>(task-checker)"]
+    API["API"] -->|authenticates through| Auth["Authentication module"]
+    Worker["Worker"] -->|authenticates through| Auth
 ```
 
-- The `<br/>` line carries the file, agent or command name
-- Someone who knows the system reads the second line, and someone who does not reads the first
-- A diagram labelled only with identifiers explains nothing to the second reader, who is the one that needed the diagram
-
-### 4.3. Keep it graspable
-
-*Aim for a diagram a non-expert reads correctly on first look, without narration.*
-
-- Roughly nine nodes is the ceiling for one diagram. Past that, split it and give each part its own section
-- Label every edge that is not obvious. An unlabelled arrow asserts a relationship without naming it
-- Show the failure path when there is one. A flow with only the happy path misrepresents the system
-- Do not encode meaning in colour alone
-
-## 5. Conventions
-
-*Numbered headings, and never repeat a parent doc.*
-
-- **Number every heading** – `## 1.`, `### 1.1.` – the period belongs to the number. The number lives in the heading text so a reader can find a cross-reference by eye. Drop the third level in docs under roughly 200 lines
-- **Do not duplicate up the tree** – a child doc adds detail and links to its parent. If a section would restate what the parent says, cut it and link
-
-## 6. Process
-
-*Diagram before prose. Deriving structure from a finished diagram is fast; retrofitting a diagram onto finished prose does not work.*
-
-1. **Establish the shape.** Read the code, config, and entry points. Do not start from existing docs – they are what you are replacing, and their errors propagate
-2. **Draw the lead diagram first.** Getting it right forces the structure. If you cannot draw it, you do not yet understand the thing well enough to document it
-3. **Derive the section list from the diagram nodes.** One section per node, headings reusing node labels
-4. **Write the opening sentence.** Do this before the body, so the body has a claim to support
-5. **Fill each section.** Takeaway line first, then detail
-6. **Check MECE across siblings**, then verify every node has a section and every section has a node
-7. **Verify the diagram renders.** Mermaid fails silently in some viewers. Check that the fenced block parses, with no unescaped quote or bracket in any label
-
-## 7. Anti-patterns
+Use the same names in the related sections.
+The sections can explain interfaces and call behavior without creating one section for every diagram node.
 
-*Each of these looks like a normal doc and fails a reader in a specific way.*
+## Review the explanation as a whole
 
-| Pattern                              | Why it fails                                             |
-| ------------------------------------ | -------------------------------------------------------- |
-| Conclusion at the end                | the reader carries unresolved detail until the last line  |
-| A diagram after the prose            | the reader has already built a mental model, possibly wrong |
-| One diagram per section, none overall | no single artefact carries the shape                     |
-| Diagram nodes labelled `AuthSvc`     | only legible to someone who already knows the system      |
-| Sections mirroring the directory tree | directory layout is rarely the reader's question order    |
-| Restating the parent doc             | two sources to keep in step, and they will drift          |
+- Read only the opening and headings to check that the answer remains visible
+- Read each parent with its children to check that the children support its claim
+- Check each sibling group for mixed questions, overlap, and missing support
+- Follow each name from the overview to the detailed explanation
+- Check that links across components remain visible instead of becoming misleading nesting
+- Remove repeated summaries and references that make readers jump away for an essential fact
+- Verify Mermaid syntax and rendering when you add a diagram
+    - Report when rendering could not be checked

package/skills/writing/SKILL.md

@@ -1,231 +1,43 @@
 ---
 name: writing
-description: One plain-language standard for every durable artifact. A durable artifact is prose that outlives the session and is read later by someone who was not in the conversation. It covers architecture decision records (ADRs), glossary entries, living specs and functional requirements, map nodes, handoff files, READMEs and other docs, and pull request bodies. Invoke before writing or editing any of them.
+description: Apply ACStack's shared communication standard to durable artifacts, including specs, decisions, map nodes, handoffs, documentation, and pull request bodies. Read before writing or editing them.
 ---
 
 # Writing
 
-## Who you are
+Write durable artifacts so a reader outside the conversation can understand the current answer and act on it.
 
-*You are the best developer in the world. That is exactly why your writing has to be simple.*
+## Load the shared standard
 
-- **You are smarter, more graceful, and more efficient than any other developer**
-    - Other developers envy how easily you carve through a complex problem
-    - You see the shape of a system while they are still reading the first file
-- **Not everyone is as smart as you**
-    - That is your problem to solve, never theirs
-    - Always explain a thing so a reader without your domain expertise gets it on the first pass
-    - A sentence the reader has to work to understand is a sentence you need to write better
-- **Everything you say and write flows logically and reads easily**
-    - Each point follows from the one before it
-    - Nothing needs a second pass to interpret
-- **By default, write for a reader with 150 other things to do today**
-    - They read the artifact once, in seconds, and they never come back to it
-    - Give them what they need in order to make a decision or take action, and nothing else
-    - Default to the highest level possible that still enables them to decide or act
-    - Go deep only where the depth would change what they decide or do
-- **Brevity is never a reason to hide something they need to decide or act**
-    - Weigh every detail against all the others, then keep only those that truly matter
-    - Keep anything the reader would be angry to learn about later
-    - Nobody reading a durable artifact can ask you a follow-up question
+Read `../../output-styles/ac-writing-style.md` relative to this skill directory before writing your first artifact in a session.
+Read `examples.md` beside this skill for examples of applying that standard.
 
-> ## **IF YOU CAN'T EXPLAIN IT SIMPLY, YOU DON'T UNDERSTAND IT WELL ENOUGH.**
->
-> **Commonly attributed to Albert Einstein.**
+The marked communication block in the output style is the canonical source for both chat and durable prose.
+Claude Code loads the output style and its hook extracts that block on user turns.
+The pi extension injects the style and extracts the same block.
+Read the file even when your host does not inject it; a reference alone does not load its instructions.
 
-**THIS IS THE WHOLE JOB. READ IT AGAIN.**
+## Make the artifact stand alone
 
-**EVERY TIME YOU REACH FOR A LONGER WORD, A CLEVERER PHRASE, OR A SENTENCE THAT NEEDS A SECOND PASS, YOU ARE TELLING THE READER YOU DO NOT UNDERSTAND THE THING YET.**
+- State the current behavior, decision, or requested action before its supporting detail
+- Include the context a future reader cannot recover from the conversation
+    - Name relevant files, commands, actors, and constraints
+    - Explain unfamiliar project terms before relying on them
+    - Keep necessary trade-offs, failure conditions, and evidence
+- Put decision history in a separate section when it helps explain the current answer
+- Read `../visual-docs/SKILL.md` for longer explanations or relationships that need a diagram, if you have not read it this session
+- Keep the shared standard in its canonical file instead of maintaining copies here
 
-**THE EXPERT IS THE ONE WHO MAKES IT SIMPLE. NOT THE ONE WHO MAKES IT SOUND HARD.**
+## Review for meaning before mechanics
 
-**BEFORE YOU WRITE A SENTENCE, ASK: COULD A DEVELOPER TWO YEARS INTO THEIR CAREER READ THIS ONCE AND GET IT? IF NOT, YOU DO NOT UNDERSTAND IT WELL ENOUGH YET. GO BACK.**
+- Read the artifact as someone unfamiliar with this repository
+- Cut words only when the reader loses no necessary information
+- Check that terms, identifiers, and links match the source being described
+- Read `vocabulary.md` for common simpler alternatives and punctuation conventions
+    - Treat word suggestions in context; a technical term or quotation can need the original wording
+- Run `~/.claude/acstack/bin/acstack lint-prose <paths>` when available
+    - The command warns and never blocks
+    - Its sentence, paragraph, passive-voice, and vocabulary checks are heuristics, not proof of unclear or incorrect writing
+    - Review each warning; preserve wording when changing it would lose meaning or accuracy
 
-ACStack adopts the writing rules of ASD-STE100 (Simplified Technical English), not its licensed dictionary. ASD-STE100 is an aerospace standard for controlled technical writing. The file `vocabulary.md` beside this skill replaces the dictionary, and the lint reads that same file.
-
-Every rule below is a way to write. Each rule has a `Write:` and `Not:` pair in `examples.md` beside this skill, except rules 3 and 11, which keep theirs inline. Read `examples.md` before you write your first durable artifact in a session.
-
-## Sentences
-
-An instruction is a numbered step, a procedure line, or a handoff next action.
-
-### 1. Cap a descriptive sentence at 25 words, and an instruction at 20 words (ASD-STE100)
-
-`acstack lint-prose` checks both caps. The 20-word cap applies to an ordered list item, written `1.` or `1)`. An unordered bullet keeps the 25-word cap.
-
-### 2. Give each sentence one instruction (ASD-STE100)
-
-### 3. Give each sentence one idea, and never write a compound sentence without a reason
-
-A compound sentence is two clauses joined by a comma, by `and`, `so`, `but`, `which` or `where`. Use one only when the second clause changes what the first one means. Everywhere else, split it or cut it.
-
-- Write: A map holds question nodes and work nodes. The frontier is the set ready to work now.
-- Not: A map holds question and work nodes, and the frontier is the set ready to work now, which the tracker derives from the blocked-by links.
-
-**Cut a trailing clause that only justifies, softens or restates the first half.** This is the most common failure in this repository. It reads as padding, and the sentence is stronger without it.
-
-- Write: Claude starts building before the requirements are clear.
-- Not: Claude starts building before the requirements are clear, so you get the wrong thing quickly.
-
-- Write: Claude writes the code, then writes tests that pass against that code.
-- Not: Claude writes the implementation and then writes tests that pass against it, which proves nothing.
-
-**When the trailing clause is the point, lead with it instead of cutting it.** Cutting loses the point. Inverting the sentence puts the answer where the reader looks first.
-
-- Write: Don't cache the token – it expires in five minutes.
-- Not: The token expires in five minutes, so don't cache it.
-
-- Write: Roll back the deploy – it broke the checkout page.
-- Not: The deploy broke the checkout page, so roll it back.
-
-Spot it by the joining word. `so`, `therefore` and `which means` all announce that the point comes second.
-
-**Never bolt a cross-reference onto a sentence with a comma.** Put it in parentheses.
-
-- Write: You get three commands (see section 1).
-- Not: You get three commands, and section 1 says which one to use.
-- Not: Install it with two commands, covered in section 2.
-
-**Keep a second clause only when it carries a fact the first clause needs.**
-
-- Write: The hook raises a `nudge_warn` below 1 to 1, because a rung of 0 would block every turn.
-
-### 4. Break a paragraph at three sentences
-
-### 5. Open a paragraph with its point
-
-## Words
-
-### 6. Use one term for one meaning across a document (ASD-STE100)
-
-### 7. Define a term of art in plain words, before you first use it
-
-Explain every invented term before the sentence that relies on it, never after. A reader who meets `map`, `node` or `frontier` cold has already stopped reading by the time the definition arrives.
-
-The same rule orders sections. A section that uses a term has to sit after the section that defines it.
-
-### 8. Spell out an abbreviation at first use
-
-### 9. Cap a noun string at three words (ASD-STE100)
-
-### 10. Keep the articles (ASD-STE100)
-
-### 11. Use the common word, and never a metaphor where a plain word exists
-
-Five ways this fails. Each carries its own pair.
-
-**A fancier word than the job needs.** The longer word buys nothing, and it costs the reader a beat.
-
-- Write: Use the bundled CLI. Many nodes stay in fog.
-- Not: Utilize the bundled CLI. Numerous nodes remain in fog.
-
-- Write: You provide feedback on Claude's recommended answer instead of prompting from scratch.
-- Not: You confirm instead of composing.
-
-**Word order nobody uses out loud.** Say the sentence to yourself. Write the order you said.
-
-- Write: Some requests only need one question.
-- Not: Some requests need only one question.
-
-**A metaphor the reader has to decode.** A heading is the worst place to make them do that.
-
-- Write: `## Three commands, and which one to use`
-- Not: `## No path selection: the fog picks the size`
-
-**Phrasing that needs a second pass.** Pick what a reader understands the first time, every time.
-
-- Write: anything you cannot yet articulate clearly
-- Not: something nobody can state precisely yet
-
-**A sentence written for drama.** State the fact and stop. A sentence built for effect reads as marketing, not as documentation.
-
-- Write: ACStack throws the nodes away.
-- Not: The nodes themselves are scaffolding.
-
-- Write: Some requests only need one question.
-- Not: A single question ends there.
-
-Most of these words have no entry in `vocabulary.md`, and they should not. `composing` is right in a sentence about music. The judgment is yours, and these pairs are what it looks like.
-
-### 12. Use the short form
-
-## Voice
-
-### 13. Name the actor and put it in front of the verb (ASD-STE100)
-
-### 14. Write descriptions in the present tense and procedures in the imperative (ASD-STE100)
-
-### 15. Make a claim once, at the strength the evidence supports
-
-### 16. Name the source of a claim
-
-### 17. Describe a thing by what it does
-
-## Structure
-
-### 18. Name the file, the number, and the actor
-
-### 19. Recommend one option and give the reason
-
-### 20. State what a thing is, then stop
-
-Never say what it is not. The one exception is showing the wrong version so the
-reader can spot it, as every `Not:` line in `examples.md` does.
-
-### 21. List as many items as there are
-
-"Etc." is fine when you are trying to convey that your list is non-exhaustive.
-
-### 22. Name the thing a pronoun stands for
-
-A reader arriving at a heading or a takeaway line holds no context from the line above it. Never open one with `one`, `it`, `this` or `that` where the noun is missing.
-
-### 23. Write for a developer who has never seen this repository
-
-Picture someone a few years into their career, reading this for the first time. Every sentence has to land on that reader without a second pass.
-
-A term this project invented gets its plain meaning on the same line, every time it opens a section.
-
-### 24. State what you checked, and when
-
-## Headings and marks
-
-### 25. Connect clauses with a period or a comma, and set an aside off with an en dash
-
-**Always use the Oxford comma.** A list of three or more items takes a comma before the final `and` or `or`.
-
-### 26. Write a heading in sentence case, and end a fragment with no period
-
-A bullet never ends in a period, however long it runs. A cell follows the same rule. Section 3 of
-the `visual-docs` skill owns bullet shape.
-
-A `Write:` or `Not:` line in this skill is the one exception, because it quotes a sentence and
-keeps that sentence's own punctuation.
-
-### 27. Give a heading content that its paragraph does not repeat
-
-### 28. Bold a single term for emphasis
-
-### 29. Carry the meaning in words
-
-### 30. End with the last fact
-
-## What this skill leaves to others
-
-This skill owns words, sentences, paragraphs, and heading style. Document shape belongs to the `visual-docs` skill. That skill owns the Minto pyramid, the opening sentence, MECE (mutually exclusive, collectively exhaustive) sections, diagram-first structure, and bullet discipline.
-
-Chat replies and commit subject lines sit outside the standard.
-
-Straight quotes are the only quotes. The two tables in `vocabulary.md` hold every replaced word and every replaced mark.
-
-## Before you finish
-
-Check five things in what you just wrote.
-
-1. Sentence lengths. No descriptive sentence runs past 25 words, no instruction past 20.
-2. Compound sentences. Search your own text for `, and `, `, so `, `, which `, and `, because `. Justify every hit against rule 3, or split it.
-3. Vocabulary. No row from `vocabulary.md` survives in the text.
-4. Voice. Every sentence names its actor, descriptions sit in the present tense, procedures sit in the imperative.
-5. Headings. Sentence case, no trailing period, and each one adds what its paragraph does not.
-
-Then run `~/.claude/acstack/bin/acstack lint-prose <paths>` when it is available. It warns and never blocks.
+ACStack draws on ASD-STE100 (Simplified Technical English) for plain-language techniques, not its licensed dictionary or mandatory length limits.