Terseness Techniques – an upcoming addition to documentation-discipline for https://github.com/automician/docs-for-agents/

LICENSE

MIT License

Copyright (c) 2026 Yakiv Kramarenko

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

terseness-techniques.md

status	active
created	2026-06-03
type	techniques-note
parent	delivery-2026-06
license	MIT © 2026 Yakiv Kramarenko.

AI-native doc terseness — techniques from the flag-on-read refactor

Captured 2026-06-03 (Yashaka's request) from the flag-inconsistency-on-read wisp series (wisp1 draft 79 → wisp4 66 lines, ~56 walk-up-effective). Three uses: (1) the light-pass checklist for the other comparable-size to-be-shipped artifacts; (2) seed for the deferred documentation-discipline terseness/style enhancement (promote there when it activates); (3) course material — a worked example of refactoring AI-native documentation.

The wisp chain itself is preserved verbatim beside this file as flag-on-read.wisp{1..4}-*.local.md (untracked).

Content / de-duplication

1. One idea, one home. The cost-of-silence was stated three times (opening + Why ×2). Fix: assert once, explain once — a claim made in the opening is not re-argued later; the Why explains it, doesn't restate it.
2. Opening = WHAT + hook; Why = the reasoning. Split them so they don't overlap: the opening carries the principle plus a one-clause hook ("the read already paid for the noticing"); the Why owns the rationale.
3. Chase redundancy, not line-count. The shrink came from removing duplication, not from cutting substance. A lean doc says each thing once, not less. (Redundancy includes redundancy-against-structure — position / handle / neighbours — not only against other prose: #15.)

Cross-references

4. One gloss, one home — inline / Connected. A link's REASONING lives in one place: load-bearing at a point → inline there; family / lineage that aids understanding (no inline home) → the visible Connected principles section, one-line "why related" each — don't duplicate that gloss across the two. A bare ## Cross-refs meta-comment index was once a candidate third form (complete-by-design for orient-read), but ADR-030 retired it: discoverability is grep-derived, not index-maintained — the "lists everything" premise does not hold. Two homes only; the full inventory is a grep (fix-cross-refs). (Cut flag-on-read's Connected 5 → 2.)
5. Don't add a dependency you can state self-contained. A cited-but-not- load-bearing ref (transparency-as-equilibrium) → expressed the idea in the article's own words, dropped the citation. Cite when you genuinely lean on the upstream; not for lineage decoration (each ref is also a gloss/delink cost at OSS-copy time).
6. Name the upstream concept; don't re-derive it. The Why names "paraphrase-drift" (defined upstream in documentation-discipline § SSOT) instead of re-explaining the mechanism. The reference is the explanation (SSOT). (When no upstream term exists yet for a recurring enumeration, coin one: #16.)
7. Cross-ref direction — up or sideways, never down. Reference upstream (what you build on) or sideways (a peer / sibling — e.g. one constitution article to another); never down to a consumer — a downward ref inverts the dependency. Foundational / ambient terms (defined in the always-loaded base, e.g. piece ← coordination-substrate) are used freely, no inline cite — you don't footnote each word against a dictionary. (Placement — inline vs Connected vs meta-comment — is technique 4.) Caught: todos-convention's inline workflow-piece down-ref — dropped; workflow-piece is a consumer (downstream), and the discoverability pointer already lives in the bottom meta-comment. Promote-target (deferred from delivery-2026-06 Stage 1): codify this up/sideways/never-down layering rule as convention in documentation-discipline + a mention in rule-content-review.

Structure

8. Merge two phrasings of one rule — keep the actionable form. "Don't resolve unilaterally" overlapped the scale-bullet's "unclear → raise"; the "balloon" anti-pattern duplicated the "Flag and continue" how-to. Kept the positive directive, dropped the inverse.
9. A section heading must earn its weight. After the merge, Anti-patterns held one genuine item plus inversions → dropped the section, folded the survivor into the practice list. Anti-patterns earn their place only when they name a non-obvious failure mode — not an inversion of a stated how-to. (Optional section: siblings no-premature-closure / transparency have none, so dropping it stays sibling-consistent.)
10. Match sibling structure unless changing the convention everywhere. Kept the visible Connected principles section (siblings have it) rather than unilaterally restructuring — in a showcase of doc-method, an odd-one-out reads as half-baked. Local-clean now; general structural questions deferred, not decided unilaterally under deadline.

Principle-article discipline

11. State the principle, delegate the mechanism. The scale-bullet doesn't hardcode marker semantics (! / :) or channel — it delegates to todos-convention + workflow-piece ("durable marker / raise / never chat-only"). Keeps an always-loaded article lean and future-compatible (won't contradict sibling / downstream specs).
12. Keep the "why constitutional" elevation — but terse. The autonomy / scale paragraph stays (it's what makes it constitutional vs a mere style tip), compressed and leaning on upstream-naming (technique 6).

Meta / process

13. Meta → HTML comment. Provenance, open questions, hoist-candidates, trigger-to-revisit → HTML comment (walk-up strips it = free; dropped at OSS-copy), never the body.
14. Dogfooded process moves: flag-don't-silently-decide on review deltas (surfaced the manifest-deviation rather than silently adding/omitting); lean-first when presenting options; honest disagreement on scope (resisted "lay across all models" + deep-audit-all); decisions → PLAN/manifest (forward home), not chat; preserve the wisp chain as a durable artifact.

Structure & abstraction

Harvested 2026-06-09 from the workflow-piece § Per-piece iteration refactor (per-piece-loop-precondition-review Piece 3) — higher-order moves above the tactical de-dup / cross-ref techniques.

15. Structure is context — don't restate what position, handle, or neighbours already encode. A numbered step, its bold lead-in, the words already in the line, the adjacent steps carry meaning; prose re-deriving it is inert redundancy — cut it, even dressed as a clarification or an "X, not Y" caveat. Trap: an "is it load-bearing?" check skews to KEEP (you can always invent a use); ask "does the surrounding structure already make this unambiguous?" instead. Carve-out — emphasis ≠ inert: a deliberate, sparing restatement whose job is a recall handle (a quotable principle / evocative inversion the reader would lose — cf. #2's hook + documentation-discipline § Terse principle phrasing) earns its place. Discriminator: a recall-handle / rhetorical landing, or just a repeated fact? Guard the carve-out: ≤1 per passage — if everything is a punchline, nothing lands. (Cut: Step-1's "wisps accumulate…, not within this step" — the handle's "one" + the loop heading already carry it. Keep: documentation-discipline-trigger's "the Edit is the last step, not the first" — crystallises the bullet into a sticky handle.)
16. Coin an upstream umbrella to collapse downstream enumerations. When ≥2 downstream sites re-list the same set (questions / proposals / concerns…) because no term names it, the fix isn't to cite — there is nothing to cite yet — it's to define the umbrella upstream (a true genus over the cases), then have downstream cite the one handle. Buys downstream terseness + SSOT (the set's definition gets one home) + extensibility (a new kind extends the term, not every site). The doc analog of extract-a-variable / introduce-a-type. Pairs with #6 (which assumes the concept exists; this one creates it). Guardrail (no-premature-closure): coin only when the enumeration genuinely recurs AND the term is a real genus — covers the cases natively, name-coheres with its home, earns a definition; else premature abstraction. (todos: defining todos upstream collapsed Step 2 to "leaving todos per todos-convention".)