Skip to content

feat: plain-English output for everything a person reads - #119

Merged
rshankras merged 1 commit into
mainfrom
feat/115-plain-output
Nov 6, 2026
Merged

rshankras merged 1 commit into
mainfrom
feat/115-plain-output

Conversation

@rshankras

Copy link
Copy Markdown
Owner

Closes #115.

In plain words

SwiftShip's reports and finish messages were written for experts. Now they open with one everyday sentence saying what happened and whether you need to do anything. Technical words get explained, and every message ends by saying what (if anything) you need to decide. The checks and evidence are unchanged; only the wording is different.

What changed

  • New shared rule templates/_conventions/PLAIN-OUTPUT.md. It covers:
    • the plain first sentence
    • explaining terms the first time they appear
    • saying what each number means
    • short sentences with no stacked abbreviations
    • tables after the summary, never instead of it
    • a closing "You need to decide" line
    • explained status words (PASS / PARTIAL / FAIL)
    • a checklist to run before printing
  • Reader setting: a reader: plain | technical line in PREFERENCES.md. The default is plain. /apple:discuss asks it once, whatever the phase.
  • Applied to:
    • verify: an "In plain words" line in VERIFICATION.md (command and template), plus the completion message
    • review: an "In plain words" line in REVIEW.md, a "What this means" line for each Critical/High finding (who is affected and how), plus the completion message
    • build: a plain line for each finished task and for the end of the phase
    • debt: the completion message and DEBT.md's top line
    • map: the completion message and CODEBASE.md's top line
  • If the convention file is missing (older install), commands write as before.
  • Other changes: a CLAUDE.md "Plain Output" section and a CHANGELOG entry.

Tested

  • ./scripts/validate.sh passes, and claude plugin validate . passes.
  • Not tested: output wording on a real run. The next real verify or debt run will show it.

🤖 Generated with Claude Code

…115)

New PLAIN-OUTPUT convention: one plain first sentence, terms explained,
numbers given meaning, a closing 'You need to decide' line. reader:
plain|technical in PREFERENCES.md (default plain), asked once by
discuss. Applied to verify, review, build, debt and map completion
messages and report tops.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rshankras
rshankras merged commit b8e2c1b into main Nov 6, 2026
2 checks passed
@rshankras
rshankras deleted the feat/115-plain-output branch November 6, 2026 07:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: plain-English output for everything a person reads

1 participant