diff --git a/docs/standards/README.md b/docs/standards/README.md new file mode 100644 index 0000000..3435bb2 --- /dev/null +++ b/docs/standards/README.md @@ -0,0 +1,18 @@ +--- +standards-contract: 1.0.2 +--- + +# Standards index + +Team-layer engineering standards synced from melodic-software/standards +(`conventions/engineering/`). Change them there, not here. + +| Surface | Applies when | File | +|---|---|---| +| bulk-mutation | a command or sweep that creates, deletes, or changes many objects; background or unattended runs; work spanning several targets | bulk-mutation.md | +| concise-prose | writing or reviewing any prose: docs, comments, commit messages, PR bodies, replies | concise-prose.md | +| deterministic-work-execution | counts, diffs, sorting, arithmetic, inventories; composing shell commands an agent runs | deterministic-work-execution.md | +| documentation-and-citations | citing upstream docs; recording an external default or version; labeling the basis of a recommendation | documentation-and-citations.md | +| reference-dont-duplicate | a fact, value, or rule appearing in more than one place; origin or history notes in code or docs | reference-dont-duplicate.md | +| simpler-code | writing or reviewing code; proposing a new check, process, document, or dependency; serializing work; keeping an existing mechanism | simpler-code.md | +| source-authority-tiers | grounding a recommendation, option, or decision; judging how much a source is worth | source-authority-tiers.md | diff --git a/docs/standards/bulk-mutation.md b/docs/standards/bulk-mutation.md new file mode 100644 index 0000000..6f09afa --- /dev/null +++ b/docs/standards/bulk-mutation.md @@ -0,0 +1,36 @@ +# Bulk mutation + +A command that creates, deletes, or changes many objects at once is only as +safe as the scope it runs over. This convention covers bounding that scope +before the command runs. It is a reasoning-only judgment: a tool can report a +count, but only the author can tell whether the scope matches what was meant. + +## The scope sets the blast radius + +A policy flag such as "delete everything not yet handled" or "install all +missing" does not decide how much it touches; the scope argument beside it +does. The same wording is safe over a curated set and destructive over every +set the machine knows about. Before a sweep runs unattended, resolve how many +objects it will create, delete, or modify, and state that number. + +## Count first, then act + +Count before acting whenever a run does any of the following: + +- runs in the background or unattended; +- spans more than one target; or +- inherits an automatic policy that someone configured with a narrower case + in mind. + +## Running unattended does not grant consent + +A background task needs the confirmation it would get if run interactively. +Running it unattended removes the person from the loop, not the need for their +approval. An automatic policy that an unattended run inherits drops to its +confirm-first variant rather than standing in for consent. + +## Boundaries + +- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-work-execution.md)**: + that file covers producing the count honestly by running a tool. This file + says when the count is required and what to do with it. diff --git a/docs/standards/concise-prose.md b/docs/standards/concise-prose.md new file mode 100644 index 0000000..d53994b --- /dev/null +++ b/docs/standards/concise-prose.md @@ -0,0 +1,84 @@ +# Concise prose without semantic loss + +Write prose as briefly as clarity and completeness allow. Remove words only +when the result preserves the same meaning and remains as easy to apply. This +is a reasoning-only judgment: word or sentence counts can flag a passage for +review, but they cannot prove that a shorter version is equivalent. + +This rule owns wording, not whether content belongs or where it lives. +[`documentation-existence.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-existence.md) owns whether a +page may exist at all; +[`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md) owns reductions to executable code; +[`progressive-disclosure.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/progressive-disclosure.md) owns information +layering; and [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md) and +[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md) jointly own +whether a fact stays inline or is cited. [`naming.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/naming.md) owns +identifiers, and [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/legacy-and-migration-debt.md) +owns whether historical narration belongs at all. Apply this convention to the +prose that remains after those decisions. + +## Remove non-semantic overhead + +Cut filler openings, empty intensifiers, reflexive hedges, unnecessary +modifiers, repeated restatements, and multi-word phrases that a precise word +can replace. Keep a hedge or qualifier when it communicates real uncertainty, +confidence, or scope. The test is whether each word adds meaning or helps the +reader act; +[Digital.gov](https://digital.gov/guides/plain-language/principles/short-simple) +and the +[Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences) +recommend removing words that add no substance. + +Do not vary terminology merely to avoid repetition. Use one term for one +concept. Repeat a word deliberately when the repetition prevents ambiguity or +keeps parallel conditions explicit, as Google's +[global-audience guidance](https://developers.google.com/style/translation#use-helper-words-and-optional-words) +recommends. + +State the point literally. Where a plain phrase says it, use that phrase +instead of a metaphor or flourish: figurative wording makes the reader +translate it back into the claim, and the translation can go wrong. + +## Preserve the whole contract + +A shorter version is wrong when it changes what the reader must know or do. +Keep all of the following when they carry meaning: + +- normative force, scope, actors, and required actions; +- conditions, exceptions, alternatives, and ordering; +- thresholds, defaults, units, and other exact values; +- definitions and context needed to remove ambiguity; +- rationale needed to evaluate or maintain a decision; and +- examples needed to understand a concept or apply a rule. + +Do not turn explicit content into an inference the reader must supply. W3C's +[supplemental cognitive-accessibility guidance](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p12-implicit-explained/) +recommends explaining implied or ambiguous information; it informs this clarity +judgment but is not conformance-required WCAG guidance. + +## Shorten structure, not meaning + +Prefer one point per sentence and one topic per paragraph. Split compound +thoughts, lead with the point or condition that governs what follows, and use a +list when several parallel items must remain distinct. Digital.gov's +[clear-and-short guidance](https://digital.gov/guides/plain-language/writing/clear-short) +and W3C's +[succinct-text pattern](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p05-succinct-text/) +use this structure to make information easier to process. + +Length is a review trigger, not a target. A long sentence or paragraph deserves +a clarity check; keep it when splitting it would obscure a relationship, add +redundancy, or make the prose less natural. A short passage still fails when it +is incomplete, ambiguous, or abrupt. + +## Sources + +- [Digital.gov, "Short and simple"](https://digital.gov/guides/plain-language/principles/short-simple) +- [Digital.gov, "Clear and short"](https://digital.gov/guides/plain-language/writing/clear-short) +- [Microsoft Writing Style Guide, "Use simple words, concise sentences"](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences) +- [Microsoft Learn style and voice quick start](https://learn.microsoft.com/en-us/contribute/content/style-quick-start) +- [Google developer documentation style guide, "Write for a global audience"](https://developers.google.com/style/translation) +- [W3C cognitive accessibility pattern, "Keep Text Succinct"](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p05-succinct-text/) +- [W3C cognitive accessibility pattern, "Explain Implied Content"](https://www.w3.org/WAI/WCAG2/supplemental/patterns/o3p12-implicit-explained/) +- [GOV.UK, "Publishing accessible documents"](https://www.gov.uk/guidance/publishing-accessible-documents) +- [ISO 24495-1:2023, *Plain language — Part 1: Governing principles and guidelines*](https://www.iso.org/standard/78907.html) diff --git a/docs/standards/deterministic-work-execution.md b/docs/standards/deterministic-work-execution.md new file mode 100644 index 0000000..23cc9af --- /dev/null +++ b/docs/standards/deterministic-work-execution.md @@ -0,0 +1,108 @@ +# Execute deterministic work with tools + +When a task contains a substep that a mechanical procedure can decide, run the +narrowest existing tool, query, calculator, interpreter, or disposable script +that fits, then reason over its actual output. Do not hand-count, mentally sort, +or imitate execution in prose when the operation can run. Writing code-shaped +text without executing it produces no result. + +The policy is grounded in a bounded body of evidence. PAL and Program of +Thoughts improved performance on the numerical, symbolic, and algorithmic +tasks they studied by delegating execution to an interpreter +([Gao et al.](https://proceedings.mlr.press/v202/gao23f), +[Chen et al.](https://openreview.net/forum?id=YfZ4ZPt8zd)). Toolformer found a +similar benefit from calling specialized tools, including a calculator, instead +of asking one language model to supply every result +([Schick et al.](https://proceedings.neurips.cc/paper_files/paper/2023/hash/d842425e4bf79ba039352da0f658a906-Abstract-Conference.html)). +Those studies do not prove that every generated program is correct. The policy +inference is narrower: once a substep has a complete mechanical specification, +its result should come from executing that specification rather than predicting +the result in text. + +## Classify each substep before executing it + +[`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md) owns the tier definitions. +Apply them to the current substep, not to the task as a whole: + +- For **deterministic** work, execute the operation and consume the returned + result. Examples include an exact count or diff, arithmetic, sorting by a + declared key, matching a declared pattern, a syntax-aware transformation, or + a repository-wide inventory over an explicit path set. +- For **detect-then-judge** work, execute only the detection half. The result is + a candidate set; a human or agent still rules on every candidate. A similarity + score, heuristic match, or advisory scan cannot promote its own flag to a + verdict. +- For **reasoning-only** work, do not encode the verdict in a script. A tool may + gather deterministic evidence for the judgment, but meaning, intent, fit, and + semantic equivalence remain with the human or agent. + +Classification is itself reasoning-only. A task that mixes exact inventory with +architectural judgment therefore gets an executed inventory followed by a +reasoned decision, not one mechanism pretending to own both. + +## Make the execution honest + +A script is not deterministic merely because it is code. Before relying on its +output: + +- state the operation, input scope, comparison rule, and ordering explicitly; +- prefer a mature existing tool over generating new logic when both implement + the same operation; +- run the command or script and inspect its exit status and material output; +- check nontrivial generated logic against a known case, invariant, or second + representation in proportion to the consequence of a wrong answer; and +- record the invocation, input scope, and material result when they support a + change or verification claim, so another reader can repeat the computation. + +Successful execution proves only that the encoded operation ran. It does not +prove that the inputs were complete, that the operation answered the intended +question, or that a later judgment is sound. The National Academies report +defines computational reproducibility around the same inputs, computational +steps, methods, code, and conditions of analysis +([*Reproducibility and Replicability in Science*](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science)). +The UK Government Analysis Function likewise recommends minimizing manual steps +while retaining quality assurance and an audit trail +([RAP strategy](https://analysisfunction.civilservice.gov.uk/policy-store/reproducible-analytical-pipelines-strategy/)). + +## Keep session-time work in its lane + +This convention governs one-off execution during the current task. It does not +require committing a throwaway script, adding a dependency, or building a +general utility. If the same deterministic finding recurs, route it through +[`enforceability-tiers.md#routing-a-recurring-finding`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md#routing-a-recurring-finding) +instead of accumulating session scripts. + +When executable logic becomes committed behavior, the simplicity, ownership, +and test obligations in [`simpler-code.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md), +[`code-organization.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/code-organization.md), and +[`../review/testing.md`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md) apply. When the concern is a +reusable artifact's fixed shape rather than an in-task computation, +[`deterministic-artifact-scaffolding.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-artifact-scaffolding.md) +owns it. Treat the output as proof only of the exact structural or computational +claim it checked; the verification-honesty criteria in +[`../review/testing.md#verification-honesty`](https://github.com/melodic-software/standards/blob/main/conventions/review/testing.md#verification-honesty) +own broader proof claims. + +## Keep agent-run commands plain + +When an agent runs commands through a harness that checks each command before +it runs, the command's shape decides how cheaply it is checked. Keep each one +plain: + +- absolute paths, rather than a `cd` followed by relative paths; +- no inline environment assignments (`VAR=value command`), `export`, or output + redirection; +- the harness's own file-read and search tools in place of shell reads such as + `cat`, `sed -n`, or `grep`, where it has them; +- a POSIX shell rather than PowerShell unless the command needs PowerShell, + because PowerShell starts noticeably slower on Windows; and +- a background job or the harness's wait mechanism for a long operation, never + a foreground `sleep` or polling loop. + +## Sources + +- Gao et al., ["PAL: Program-aided Language Models"](https://proceedings.mlr.press/v202/gao23f) (ICML 2023). +- Chen et al., ["Program of Thoughts Prompting: Disentangling Computation from Reasoning for Numerical Reasoning Tasks"](https://openreview.net/forum?id=YfZ4ZPt8zd) (TMLR 2023). +- Schick et al., ["Toolformer: Language Models Can Teach Themselves to Use Tools"](https://proceedings.neurips.cc/paper_files/paper/2023/hash/d842425e4bf79ba039352da0f658a906-Abstract-Conference.html) (NeurIPS 2023). +- UK Government Analysis Function, ["Reproducible Analytical Pipelines (RAP) strategy"](https://analysisfunction.civilservice.gov.uk/policy-store/reproducible-analytical-pipelines-strategy/). +- National Academies of Sciences, Engineering, and Medicine, [*Reproducibility and Replicability in Science*](https://nap.nationalacademies.org/catalog/25303/reproducibility-and-replicability-in-science) (2019). diff --git a/docs/standards/documentation-and-citations.md b/docs/standards/documentation-and-citations.md new file mode 100644 index 0000000..8e026fe --- /dev/null +++ b/docs/standards/documentation-and-citations.md @@ -0,0 +1,32 @@ +# Documentation and external citations + +A source of truth that lives outside the repo is owned by that upstream, not by you: a vendor's product docs, a framework reference, a cloud dashboard, an API reference, a registry page. Copying its content into tracked files creates a snapshot that decays the moment the upstream changes. Cite it; fetch it at read time. This complements the in-repo discipline (see `reference-dont-duplicate.md`): one governs facts you own, this governs facts someone else owns. These are reasoning-only judgments. A link checker can verify that a cited URL still resolves, but whether to cite rather than copy, and where the citation lives, is yours to decide. + +## Upstream bodies are read-on-demand + +Catalogs, defaults, schemas, flag inventories, pricing, lifecycle mechanics, and install matrices are upstream-owned. Do not recap them in tracked markdown. Link to the authority and let the reader (human or agent) fetch the current version. What the repo records instead is **policy and wiring**: the paths it commits, the decisions it made, the empirical findings it observed, and operator recipes that have no stable upstream source. + +For one fact, cite either your own policy hub or the upstream URL, not both with recap prose between them. The hub owns repo policy; the upstream owns product behavior. The narrow exception is a minimal install or verify command for which no stable upstream source exists for your exact wiring; keep that inline and point at the upstream for everything around it. + +## Place the citation where it is read + +Documentation is rarely read top to bottom. Place an upstream link at the sentence that actually defers to it, so it survives a partial read or a search hit, not only in a footer. Pages that are read whole (reference hubs, overviews) additionally aggregate their external links in a footer section so a whole-file reader sees every authority at once. Both placements together beat footer-only, because readers attend to the start and end of a document more than its middle ([Liu et al., "Lost in the Middle", TACL 2024](https://aclanthology.org/2024.tacl-1.9/)). + +## Two distinct footer kinds + +Keep research provenance separate from product documentation: + +- A **sources** footer holds research provenance, the durable reasoning behind a convention: books, talks, studies, papers. +- An **external-authority** footer holds vendor, framework, and cloud *product* documentation URLs: the living references a reader fetches for current behavior. + +## Time-bound external claims need a recheck trigger + +A recorded upstream default, version gate, or price belongs in durable content only with an explicit recheck trigger: a date, an automation, or a tracked task. Prefer linking and fetching at read time over storing a snapshot at all. A snapshot with no recheck trigger is drift waiting to happen. + +## Label the basis of a recommendation + +Every recommendation, option, or decision an author or agent presents, and every recommended number, default, limit, or "best practice" in it, carries a `Basis:` label that names where it came from: a `file:line`, a tool's output, or a URL retrieved for it in the current session, or `judgment` when no source stands behind it. The label lets a reader check the claim without re-deriving it and shows which claims rest on the author alone. + +The rule covers what is presented from now on: a reply, a pull request or issue body, a design or decision record. It does not require relabeling tracked prose written before it, and a convention document is not such a presentation: its rules rest on its sources footer. + +`judgment` is not enough for a decision that spans repositories, changes shared infrastructure, cannot be undone, or bears on security. When research cannot settle such a decision, present it as an open question that names the evidence that would settle it, not as a recommendation. diff --git a/docs/standards/reference-dont-duplicate.md b/docs/standards/reference-dont-duplicate.md new file mode 100644 index 0000000..c8e2969 --- /dev/null +++ b/docs/standards/reference-dont-duplicate.md @@ -0,0 +1,78 @@ +# Reference, don't duplicate + +Every fact has one source of truth. A consumer of that fact cites it; it never restates it. A one-line "summary" of someone else's rule is the cheapest thing to write and the most expensive to maintain: when the source changes, the copy silently drifts and readers can no longer tell which version is canonical. This is a reasoning-only discipline: a tool can flag candidate duplicates, but deciding whether two passages *mean* the same thing is a judgment. + +## Two kinds of duplication + +- **Literal**: a verbatim repeat of a value across files, such as a version pin, a port, a URL, a path, an identifier. +- **Semantic**: the same concept reworded: one rule explained three different ways across three files, one prerequisite described with different phrasing in four documents. + +Literal duplication is easy to grep. Semantic duplication is the harder, equally costly smell: every update touches N sites, divergent phrasings produce silent contradictions, and readers cannot tell which is authoritative. + +## Consolidation doctrine: ordered tests + +When two passages look duplicated, copy-count thresholds are not the decision. The Rule of Three and "share at the second consumer" are heuristics subordinated to this ordered sequence: run the tests in order; the first decisive test wins. + +1. **T1: Same knowledge or coincidental?** Identical text encoding different knowledge is a coincidence, not duplication ([Hunt/Thomas](https://media.pragprog.com/titles/tpp20/dry.pdf)); never consolidate, because consolidation actively harms. +2. **T2: Crosses an encapsulation boundary?** Bounded contexts, services, availability seams: duplication is correct by design ([DDD divergent models](https://martinfowler.com/bliki/BoundedContext.html); [event-carried state transfer](https://martinfowler.com/articles/201701-event-driven.html)). Consolidate only via an explicit shared-kernel-style decision with an owner. +3. **T3: Change-together acid test.** One fact forcing edits in multiple places or formats (including code+docs pairs) is true knowledge duplication: consolidate now, even at two copies; count is irrelevant ([Hunt/Thomas](https://media.pragprog.com/titles/tpp20/dry.pdf)). +4. **T4: Abstraction namable and stable?** Both must hold to consolidate at two copies. Cannot name it, or the shape is still changing → the [Rule-of-Three brake](https://blog.jbrains.ca/permalink/clarifying-the-rule-of-three-in-refactoring/) applies ([wrong-abstraction avoidance](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction)); namable **and** stable → two copies suffice. +5. **T5: Reversibility.** Cheap to inline back → early consolidation is low-risk; load-bearing/hard-to-unwind abstraction → demand the third occurrence as evidence ([Rainsberger](https://blog.jbrains.ca/permalink/clarifying-the-rule-of-three-in-refactoring/)). +6. **T6: Churn/friction.** High co-change frequency multiplies drift cost → consolidate earlier; static content tolerates copies longer ([DITA single-sourcing](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part1-base/archSpec/base/single-sourcing.html); [Write the Docs reuse caveats](https://www.writethedocs.org/conf/portland/2022/speakers/#speaker-anna-gasparyan-don-t-shoot-yourself-in-the-foot-with-content-reuse-anna-gasparyan)). + +**Prose overlay:** knowledge-bearing docs content (values, procedures, policy) consolidates when T3–T6 say so. DITA single-sourcing is the mechanism for many deliverables from one source, not a first-reuse timing rule; audience-, context-, or SEO-sensitive prose is legitimately duplicated (Write the Docs reuse caveats); reuse-eligibility alone never justifies consolidation. + +The Rule of Three is not a cost calculus: the claim that three copies makes maintenance cost definitively outweigh refactoring cost was refuted. It is a heuristic brake against premature wrong abstractions, permissive about two, never a prohibition on earlier extraction when T3–T6 say consolidate. + +## Smell signals: any one triggers the doctrine + +1. One change edits the same fact in multiple places or formats (including a code+docs pair): run T3. +2. A search finds near-matches saying almost-but-not-quite the same thing: run T1 before consolidating. +3. Two files assert the same rule with contradicting nuance: never leave both authoritative; run T1–T3. + +## Classify a file's role before flagging + +Each file plays one of three roles toward a given fact: + +- **Describe**: the file *is* the source of truth and owns the value or concept. Keep the body here. +- **Use**: the file consumes the fact as a load-bearing reference (rules, conventions, internal docs). It must cite the source by a stable anchor rather than restate the content. +- **Expose**: the file surfaces the fact to humans for onboarding clarity (a README install command, an error message, a baseline snapshot). It *may* restate when onboarding clarity outweighs maintenance cost, and only when adjacent prose points back to the source so a future maintainer finds every copy. + +## What stays inline versus what must be cited + +**Stays inline (it is the contract surface, not duplication):** public names the source defines, such as severity tier names, label slugs, action verbs, command names, type identifiers. Naming a contract token is not copying it. + +**Must be cited, never recapped:** definitions, criteria, "when to use" descriptions, mapping tables, examples, threshold numbers, and exception clauses, meaning anything specific and subject to change. A one-line recap drifts when the source updates; the citation alone is sufficient. + +## Cite stable anchors + +Cite a source by something durable: a file's documented heading, a configuration key, a published symbol, an anchor the source intends to keep stable. Avoid citing line numbers, incidental phrasing, or internal structure that the source is free to change without notice. Prefer a link the reader can follow over a prose reference they must hunt for. + +## The code and config equivalent + +The same discipline holds outside prose. Deduplicate with the language's idiomatic mechanism rather than copying a literal across call sites: a shared constant, a build property and its reference, a YAML anchor and alias, a JSON `$ref`, an environment variable with a default. A repeated literal is both the duplication and the missing name; the named constant deduplicates and documents in one move. + +## History lives in version control + +Where and when something came from is a fact the version-control history already owns. An origin or history aside in code, comments, configuration, or docs (a "ported from" note, an "added on " comment) copies that fact into a second place nothing keeps current. Leave it out of explanatory prose, code, comments, and configuration; [`legacy-and-migration-debt.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/legacy-and-migration-debt.md) covers the related case of prose that narrates a migration. + +A record whose purpose is evidence keeps its dates and origins: a manifest's adoption, rollout, or canary notes, an architecture decision record, a component's admission evidence, a changelog. There the date is the evidence a decision rests on, not a copy of version-control history. + +## Sources + +- Hunt/Thomas, *The Pragmatic Programmer* (20th Anniv.) DRY chapter: [DRY excerpt (PDF)](https://media.pragprog.com/titles/tpp20/dry.pdf) +- Dave Thomas, Artima interview: [Orthogonality and the DRY Principle](https://www.artima.com/articles/orthogonality-and-the-dry-principle) +- Rule of Three: [Wikipedia](https://en.wikipedia.org/wiki/Rule_of_three_(computer_programming)) +- Rainsberger: [Clarifying the Rule of Three](https://blog.jbrains.ca/permalink/clarifying-the-rule-of-three-in-refactoring/) +- Fowler: [Bounded Context](https://martinfowler.com/bliki/BoundedContext.html) (quoting Evans) +- Fowler: [What do you mean by "Event-Driven"?](https://martinfowler.com/articles/201701-event-driven.html) +- OASIS DITA 1.3: [Producing different deliverables from a single source](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part1-base/archSpec/base/single-sourcing.html) +- Gasparyan, WTD Portland 2022: [Don't shoot yourself in the foot with content reuse](https://www.writethedocs.org/conf/portland/2022/speakers/#speaker-anna-gasparyan-don-t-shoot-yourself-in-the-foot-with-content-reuse-anna-gasparyan) + +Further reading (links only, not load-bearing until a targeted primary-source verify pass): [Metz, *The Wrong Abstraction*](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, AHA Programming](https://kentcdodds.com/blog/aha-programming); [Swett, counter-argument to Metz](https://www.codewithjason.com/duplication-cheaper-wrong-abstraction/); [Go proverb, copy a little](https://go-proverbs.github.io/). + +## Related + +- Whether a page may exist at all, the admission test upstream of this discipline: see `documentation-existence.md`. +- Citing authorities *outside* the repo (vendor docs, framework references): see `documentation-and-citations.md`. +- Resolving derivable external state instead of copying a snapshot of it: see `legacy-and-migration-debt.md` for the current-form-only posture. diff --git a/docs/standards/simpler-code.md b/docs/standards/simpler-code.md new file mode 100644 index 0000000..e43427d --- /dev/null +++ b/docs/standards/simpler-code.md @@ -0,0 +1,41 @@ +# Simpler code over more code + +When a unit of work can be written cleanly in fewer lines without sacrificing correctness, readability, test coverage, observability, or convention conformance, the smaller form is the default. Lines are liability: more to read, test, debug, refactor, and rename when conventions shift. This is a reasoning-only judgment: "simpler" is about intent and shape, not a character count a tool can enforce. + +## Named failure modes to avoid + +These are canonical smells, not invented ones: + +- **Speculative generality**: hooks, parameters, and special cases for a "we might need this someday" requirement that never materializes. The tell: the only callers of a function or class are its own tests. ([Fowler, *Refactoring*](https://refactoring.guru/smells/speculative-generality)) +- **The wrong abstraction**: an abstraction extracted before its shape is namable and stable (see `reference-dont-duplicate.md`, T4–T5). Duplication is cheaper than the wrong abstraction until then. Further reading: [Metz, *The Wrong Abstraction*](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, AHA Programming](https://kentcdodds.com/blog/aha-programming). +- **YAGNI violation**: configurability, plugin points, or interfaces for requirements that do not exist yet. + +## Constraints: never traded away for line count + +Reducing code must not cost any of: + +- **Clarity**: no single-letter names, no clever one-liners that hide intent, no suppressed type information. +- **Test coverage**: every behavior still has a test. +- **Error handling at boundaries**: resilience at system edges is not optional. +- **Established conventions**: dependency direction, naming, and layering hold. +- **Observability**: structured logs, traces, and metrics survive the cut. + +## Reading the reduction + +A reduction is **right** when it removes copy-paste duplication where the abstraction is namable and stable (see `reference-dont-duplicate.md`, T3–T5), collapses boilerplate into a helper, replaces a branch ladder with a lookup, uses a built-in framework primitive instead of a hand-rolled one, or deletes speculative parameters and code that only tests reference. + +A reduction is **wrong** when it suppresses an analyzer rule, drops a test, disables a lint, hides intent behind cleverness, or forces one abstraction onto two cases that are not actually the same. + +When in doubt, prefer the form that makes the next change cheaper. + +## Build only what someone acts on + +Before proposing anything new (code, a check, a process, a document, a configuration value, a dependency), name who uses its output and what they do with it. If nobody does, do not build it. When a problem has a removable cause, remove the cause rather than adding something that detects the problem or works around it. Between options that solve the same problem, count the moving parts and choose the one with the fewest. + +## No bottleneck without a reason + +Do not serialize work behind a single shared lock, a one-at-a-time queue, or a recurring manual step unless correctness or consent requires it: concurrent writes to the same state, or a person's go-ahead before a destructive change. Otherwise keep the shared thing safe by narrowing scope and protecting it, not by making it exclusive. + +## Precedent is not a reason to keep something + +An earlier answer, a design brief, or an existing pattern in the repository does not justify keeping a mechanism the evidence shows is unneeded. Say so, cite the evidence, and recommend removing it. diff --git a/docs/standards/source-authority-tiers.md b/docs/standards/source-authority-tiers.md new file mode 100644 index 0000000..4c01c49 --- /dev/null +++ b/docs/standards/source-authority-tiers.md @@ -0,0 +1,134 @@ +# Source authority tiers + +Not every source that can be cited settles a question. A claim about how a tool +behaves, what a default is, or whether an option exists is only as strong as the +distance between the claim and the thing that decides it, and that distance is +what a citation alone does not record. This convention ranks that distance and +states how much corroboration a claim needs before it is treated as settled. +[`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md) owns *whether +and where* a citation appears once a claim is accepted; this owns *what the +source is worth* and *how many are needed*. Neither answers the other's +question. + +This spans two of the tiers [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md) +defines. A source floor is **deterministic** in nature: one primary plus two +corroborators is an exact count. But the sources are named in a session, not in +a tracked artifact, so no tool has anything to count. Deciding which rung a +source occupies, and whether two sources are independent, is **reasoning-only** +regardless: it turns on what the source owns and where its content came from. +The obligation stays with the author either way. + +## The four rungs + +Authority is a function of interpretive hops, not prestige or ranking position. + +| Rung | What it is | Standing | +|---|---|---| +| **Observed** | the thing itself answering now: command output, a file's contents, an API or query response, a live configuration value | primary; a claim may rest on it | +| **Canonical** | the authority that owns the thing, read at its current version: the specification, the vendor's own reference, the source code, the changelog, the registry entry | primary; a claim may rest on it | +| **Secondhand** | someone else's account of a primary rung: a practitioner write-up, a community answer, a synthesis tool's response, a subagent's summary | corroborating only; a claim may not rest on it | +| **Recalled** | no retrieval behind it: memory, recall, an assertion whose source cannot be named | not a source; promote it to a primary rung or drop the claim | + +A **Secondhand** source is not weak because it is wrong; it is weak because a +reader cannot tell whether it is wrong without consulting the primary it +paraphrases. Naming that primary is its whole value, and it holds its rung only +while it does: one that has lost the primary it rested on, a summary of a +summary, a report whose sources are gone, has decayed to **Recalled**, whatever +it originally read. + +## Primary means owning the fact, not being reputable + +A source is primary for the facts it owns and secondhand for everything else. +The same page moves rungs with the question: a vendor's reference is **Canonical** +for its own product's behavior and **Secondhand** for a competitor's; a +specification is **Canonical** for what it requires and **Secondhand** for +whether any implementation conforms; a maintainer's post is **Canonical** for +intent and **Secondhand** for shipped behavior. Resolve the rung against the +claim, never against the domain's reputation. + +Two consequences follow. Where a claim asserts a *runtime* fact, such as what a +version does, what a flag accepts, or what actually installed, **Observed** +outranks **Canonical**: a release can ship ahead of the documentation that +describes it, so when the two disagree about behavior, the running system is the +one that decides. And a negative claim ("that option does not exist", "it was removed", +"nothing supports this") can only be carried by **Observed** or **Canonical** +retrieved for this claim: absence from a secondhand account, or from memory, is +evidence of nothing. + +## Independence is what corroboration counts + +The floor for a claim durable enough to act on is **one primary-rung source +retrieved for that claim, plus two independent corroborators of any rung**. +Corroborator count is not citation count. Two sources are one source when they +share an upstream pool, an author or author network, a generating tool, or a +single model's priors: three write-ups paraphrasing one release note are one +corroborator. + +Scale from that floor by consequence, not by convenience: + +- A claim steering reversible work inside the current session can run on the + primary alone, provided the reversal cost is low. +- A claim entering durable content, gating an irreversible action, or bearing on + security or identity needs **more primary-rung sources**, not more + corroborators. Corroboration protects against one source being unrepresentative; + it does not protect against every source being wrong. +- A claim where the retrieved sources disagree is not corroborated at any count. + Resolve the disagreement against a primary rung, or record the claim as open. + +## A rung expires with its retrieval + +A source's rung is a property of when it was read, not of the source. A fetch +from a previous session has decayed to **Recalled**: its content is now +indistinguishable from memory, and the upstream may have moved. Re-retrieve +before relying on it. This governs a source's standing as evidence; +[`documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md#time-bound-external-claims-need-a-recheck-trigger) +governs the separate obligation attached to a time-bound fact once it is written +into durable content. + +## Grounding a recommendation + +A recommendation, option, or decision put in front of someone else rests on +sources retrieved for it before it is presented, without waiting to be asked. +Ground it in both directions: + +- **Locally**: read the code, configuration, or document the recommendation + affects, and list who consumes it: callers, dependents, and other + repositories that read it. That inventory is **Observed** evidence; a + recommendation that skips it is guessing at its own reach. +- **Externally**: for a tool, version, or API, the owner's current reference + first. For a design pattern, the source that defines it (the Gang of Four + catalog, Fowler's catalogs, *Enterprise Integration Patterns*, the + domain-driven design books) and the recognized practitioners who build on + it, with publication dates and any dissent noted. A pattern's definition + does not weaken with age; a product default does. + +Adoption is not authority. A pattern found in a template, a sample, or a +popular repository shows that people use it, not that it serves the principle +it claims to. Check it against that principle before recommending it, and say +so when a common pattern fails the check. + +## Boundaries + +- **vs [`documentation-and-citations.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/documentation-and-citations.md)**: that + file owns whether a fact is cited rather than copied, where the link sits, and + which footer it belongs to. This file owns how much the cited source is worth + and how many are required. +- **vs [`reference-dont-duplicate.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md)**: that file + owns one source of truth per fact inside the repository. This file ranks + sources outside it, where there is no single owner to defer to. +- **vs [`deterministic-work-execution.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/deterministic-work-execution.md)**: + that file owns whether an execution was honest enough for its output to count + as evidence at all. This file owns what that output is worth beside other + sources once it does. A primary rung means a claim may rest on the source; it + does not mean the source answered the question that was asked. +- **vs [`enforceability-tiers.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/enforceability-tiers.md)**: that file + classifies a *convention* by who can decide it. This file classifies a + *source* by what it can establish. The two ladders are unrelated; only the + vocabulary for this document's own classification is borrowed. +- **vs [`session-time-agent-output-trust.md`](https://github.com/melodic-software/standards/blob/main/conventions/engineering/session-time-agent-output-trust.md)**: + that file governs an assertion an agent makes about its own work. An + agent's assertion carries no rung of its own; it inherits the rung of the + source it names, or **Recalled** when it names none. +- Not a research procedure. How many queries to run, in what order, and when to + stop are a consuming tool's or process's concern. This file supplies only the + ladder and the floor those procedures resolve against.