Skip to content

docs: tighten README — drop defensive framing, lead with concrete claims#182

Merged
pmclSF merged 1 commit into
mainfrom
docs/readme-tighten
May 13, 2026
Merged

docs: tighten README — drop defensive framing, lead with concrete claims#182
pmclSF merged 1 commit into
mainfrom
docs/readme-tighten

Conversation

@pmclSF
Copy link
Copy Markdown
Owner

@pmclSF pmclSF commented May 13, 2026

Summary

Tightening pass on the v1 rewrite (PR #180) after feedback that it was still too defensive and a little vague.

  • Opens with three concrete behavior claims (change a prompt, add an agent, touch a training pipeline) instead of an abstract pitch
  • Cuts the "doesn't replace Ruff / ESLint" hedge — confident products don't pre-disclaim what they aren't
  • Cuts the "What Terrain doesn't do" section entirely (six anti-claims that say nothing positive)
  • Trims the detector list from 11 to 5 — only the boundary-gap moat detectors, not the AI hygiene patterns that overlap with Semgrep / secret scanners
  • Cuts Snapshots, Policy, Architecture, and What's-stable-in-0.2 sections — all link out to docs

Length: 169 → 85 lines.

Test plan

  • Render check on GitHub
  • Detector names still match `internal/signals/signal_types.go`
  • All linked docs paths exist

🤖 Generated with Claude Code

Feedback on the prior rewrite: still too defensive, too long, hedged on
identity. This pass:

- Opens with three concrete behavior claims (change a prompt, add an
  agent, touch a training pipeline) instead of an abstract pitch
- Cuts the "doesn't replace Ruff / ESLint" hedge — confident products
  don't pre-disclaim what they aren't
- Cuts the "What Terrain doesn't do" section entirely (six anti-claims
  that say nothing positive)
- Trims the detector list from 11 to 5 — only the boundary-gap moat
  detectors, not the AI hygiene patterns that overlap with Semgrep /
  secret scanners (those live in the catalog doc, where they belong)
- Cuts Snapshots, Policy, "What's stable in 0.2 vs planned", and the
  Architecture section — all link out to docs
- Cuts Development section (build / test commands belong in
  CONTRIBUTING)

Length: 169 → 85 lines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@pmclSF pmclSF merged commit ae21064 into main May 13, 2026
@pmclSF pmclSF deleted the docs/readme-tighten branch May 13, 2026 05:31
@github-actions
Copy link
Copy Markdown

[INFO] Terrain — Informational only

Insufficient data to assess change risk confidently.

Metric Value
Changed files 1 (0 source · 0 test)

All clear. No new findings introduced; no protection gaps identified in changed code.

Run terrain compare over time to track posture; this clean state is the bar to hold.


Limitations
  • No coverage artifacts provided; protection gaps reflect missing data, not measured absence. Provide --coverage to improve accuracy.
  • Mixed test cultures reduce cross-framework optimization confidence. Consider standardizing on fewer frameworks.

Generated by Terrain · terrain pr --json for machine-readable output

Targeted Test Results

No tests selected — change affects only non-code files.

@github-actions
Copy link
Copy Markdown

Terrain AI Risk Review

Metric Value
AI surfaces 13
Eval scenarios 17
Impacted scenarios 0
Uncovered surfaces 13

Decision: PASS — AI surfaces are covered.

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.

1 participant