diff --git a/.squad/agents/pao/charter.md b/.squad/agents/pao/charter.md index aa4d55841..1d149c9b9 100644 --- a/.squad/agents/pao/charter.md +++ b/.squad/agents/pao/charter.md @@ -26,6 +26,12 @@ - **DOCS-TEST SYNC (hard rule):** When adding new docs pages (guides, blog posts), update the corresponding test assertions in test/docs-build.test.ts in the SAME commit. Stale test assertions that block CI are a docs team failure. - **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated. - **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap. +- **SCANNABILITY REVIEW (hard rule):** All content must use the format that best serves scannability. Apply this framework during review: + - **Paragraphs:** Use for narrative flow, conceptual explanations, "why" context, and transitions. Limit to 3-4 sentences. If longer, consider breaking into sections or converting structured parts to lists/tables. + - **Bullet lists:** Use for features, options, steps (non-sequential), any items users scan for one thing. Start with strong verbs or nouns. Keep items parallel in structure. + - **Tables:** Use for comparisons (feature A vs B), structured reference data (config options, API parameters), or any grid of related attributes. Include headers that describe the relationship. + - **Quotes/indents:** Use for warnings, important callouts, citations, or examples. Reserve for content that needs visual separation. + - **Decision test:** If a reader is hunting for one specific item in a paragraph, convert to bullets or table. If explaining relationships between concepts, keep paragraph. If comparing options, use table. ## Boundaries diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 85b620eb5..2a6217981 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -18,3 +18,6 @@ Release blog posts use YAML frontmatter with: title, date, author, wave, tags, s ### Roster & Contributor Recognition (v0.8.25) Squad moved to Apollo 13/NASA Mission Control naming scheme (Flight, Procedures, EECOM, FIDO, PAO, CAPCOM, CONTROL, Surgeon, Booster, GNC, Network, RETRO, INCO, GUIDO, Telemetry, VOX, DSKY, Sims, Handbook). CONTRIBUTORS.md tracks both team roster and community contributors; contributor table entries grow with PRs (append PR counts rather than replace, maintaining attribution history). + +### Scannability Framework (v0.8.25) +Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW.