Skip to content

Record in-product honesty as a safety invariant, so tone work cannot erode it #1485

Description

@Ndevu12

Context

The official site for saw is being built in a separate repository. Its copy guidance is,
deliberately, to lead with strengths and not to volunteer shortfalls — the normal and correct
register for a public landing page.

The tool's own user-facing text is governed by the opposite obligation, and for good reason:
fail closed, warn loudly, and say exactly what a verdict does and does not cover.

Both are right in their own domain. Nothing in this repository currently writes down that they
are different domains.

The risk

A future contributor — or an AI agent working from the marketing brief, a CHANGELOG entry about
"findings say the same things in fewer words", or simply good instincts about concision — could
carry the marketing register into the codebase, soften or delete a disclosure, and reasonably
believe they were following house style. There would be nothing to point at to say otherwise.

This is not hypothetical for this codebase: brevity passes have already, correctly, touched exactly
these strings.

Surfaces this protects

All of these are our own code and docs, and all are already public:

  • saw scan's host note — that a clean repository scan is not a host all-clear.
  • saw audit's scope note, and its withholding of the all-clear when the start-up surface could not
    be established.
  • The "what saw audit does not scan" table in docs/how-to/audit-a-machine.md.
  • Exit 2 and exit 3 semantics — a target that could not be scanned never reads as clean.

Precedent, which is the point

Two recent changes were the right kind of edit, and they show the line already exists in practice
even though it is unwritten:

  • 0.6.1 shortened findings considerably and moved the "does not scan" list into the documentation
    — while deliberately keeping the caveat on screen and the link to it in the report.
  • 0.6.2 fixed saw audit stating a rotation all-clear unconditionally a few lines above asking
    the reader to confirm something.

Both were judged against an invariant that no document states.

Proposal

State the obligation explicitly, in .claude/skills/saw-overview/SKILL.md alongside the other
safety invariants, and as a line in CLAUDE.md:

User-facing disclosure of scope and uncertainty is a safety invariant, not a tone or brevity
decision.
Work that shortens or rewrites user-facing text may change how a disclosure is
worded; it may not remove the claim, weaken a verdict, or move a scope statement off the run
that produced it. External or promotional copy is governed separately and never propagates
inward.

Acceptance

  • The obligation is stated in the skill and in CLAUDE.md.
  • A reviewer can cite it by name when a diff shortens a disclosure out of existence.
  • No behaviour change, no detection change; documentation and contribution guidance only.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    architectureStructural/product-shape decisionsdiscussionDecision required; not a code changedocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions