docs: AI/ML-first README rewrite (698 → 170 lines)#180
Merged
Conversation
The previous README welded three different identities together (test
control plane, AI testing tool, framework migration helper), duplicated
install + quickstart sections three times, embedded 143 lines of
not-literal example output, and never named the strategic moat. The
opening line ("control plane for your test system") said nothing about
what makes Terrain different from Codecov + Vitest + a JUnit reporter.
This rewrite:
- Leads with the moat: "Terrain is a CI gate for AI/ML codebases"
- Names the thesis: AI not a black box to the codebase, vice versa
- Centers a detector table with 11 named, shipping detectors, names
verified against internal/signals/signal_types.go
- Cuts the fake CLI output (links to docs/examples/ instead)
- Compresses Tier 1/2/3 status from 60 lines to 6
- Removes "Product Philosophy", "Who Uses Terrain", "How CI Optimization
Emerges" — they move to docs/product/vision.md, which is linked
- Consolidates three install sections into one
- One voice throughout: direct, technical, no manifesto
Length: 698 → 170 lines. Same coverage of stable capabilities, much
sharper positioning, no phantom detectors named.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
[INFO] Terrain — Informational only
Limitations
Generated by Terrain · Targeted Test ResultsNo tests selected — change affects only non-code files. |
Terrain AI Risk Review
Decision: PASS — AI surfaces are covered. |
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why now
The previous README opened with "control plane for your test system" and never explained what made Terrain different from Codecov + Vitest + a JUnit reporter. It welded together three different identities (test tool, AI tool, framework-migration tool), duplicated install + quickstart sections three times, and embedded fake example output with a disclaimer that it wasn't real. An engineer evaluating in 30 seconds couldn't tell what Terrain does.
This rewrite is aligned to the AI/ML-first strategic direction and names the killer-gap detectors that are the actual moat.
Test plan
🤖 Generated with Claude Code