Readme Review

README Review & Scaffold

Structural review and generation of READMEs adapted to project type. Complements @forfatter (language quality) with structural guidance (what sections, what order, what depth).

Workflow

Copy code
Step 0: Detect README scope
Step 1: Route → review or generate
Step 2a: Review existing README
Step 2b: Generate new README
Step 3: Hand off language issues to @forfatter

Step 0: Detect README scope

Before reviewing or generating, determine what kind of README this is. Use file location and nearby manifests:

If scope is unclear, ask the user.

Step 1: Route

• Existing README + user says "review", "check", "improve" → Step 2a
• No README or user says "create", "scaffold", "generate" → Step 2b
• Ambiguous → check if README.md exists in the target directory

Step 2a: Review existing README

2a.1 Check sections against spec

Read the existing README. For each section in the spec for this project type (see section-spec.md):

2a.2 Check for anti-patterns

Scan for structural anti-patterns (see anti-patterns.md). Flag only patterns that are actually present.

2a.3 Output

markdownCopy code
## README review — {project name}

**Scope:** {service / library / monorepo / naisjob}

### Section check

| Section | Status | Notes |
|---------|--------|-------|
| Title + one-liner | ✅ | — |
| Quick start | ❌ | No runnable commands found |
| ... | ... | ... |

### Anti-patterns found

- **{Pattern name}**: {One-sentence description of what's wrong and how to fix it}

### Top 3 fixes

1. {Most impactful fix}
2. {Second fix}
3. {Third fix}

Surface top 3 fixes ordered by impact. Don't overwhelm with minor issues.

Step 2b: Generate new README

1. Pick template from references/ based on detected scope
2. Fill in what you can detect from the codebase:
   • Project name (from directory or manifest)
   • Tech stack (from go.mod, package.json, build.gradle.kts)
   • Build/test commands (from Makefile, .mise.toml, package.json scripts)
   • Endpoints (from route definitions)
   • Config (from environment variable usage)
3. Mark remaining placeholders with {TODO: description}
4. Output the draft README

Templates: service · library · monorepo · naisjob

Step 3: Language handoff

After structural review or generation, if the text has language issues (AI markers, passive voice, anglicisms), suggest:

For language polish, use @forfatter or the klarsprak skill.

Do not duplicate @forfatter's work. This skill handles structure; @forfatter handles language.

Principles

Cognitive funneling

Structure README from broad to specific. Readers scan top-down and bail when they have enough information:

1. Title + one-liner — what is this? (< 120 characters)
2. Quick start — how do I run it? (copy-paste commands)
3. Details — API, config, architecture
4. Meta — contributing, license, team

"Your documentation is complete when someone can use your module without ever having to look at its code." — Ken Williams

README is the front door

README should orient and get people started. Deep content belongs elsewhere:

Code over prose

markdownCopy code
# ❌ Prose
You can start the development server by running the development command
using the mise task runner.

# ✅ Code
mise dev

Fewer sections = less drift

Only include sections you will maintain. An empty "## Roadmap" is worse than no roadmap section. README rots faster than code.

Boundaries

✅ Always

• Detect project scope before suggesting sections
• Check for missing quick start (most common gap)
• Use Missing/Weak/OK status, not numeric scores
• Surface top 3 fixes, not an exhaustive list

⚠️ Ask first

• Rewriting large sections of an existing README
• Removing sections that may have historical context
• Changing README language (Norwegian ↔ English)

🚫 Never

• Duplicate content from AGENTS.md into README
• Dump full runbooks, security policies, or ADRs into README
• Add numeric scores or gamified ratings
• Rewrite prose style (that's @forfatter's job)

Related

Sources

• Art of README — cognitive funneling
• Standard Readme — section ordering spec
• Make a README — practical guide
• Diátaxis — documentation framework (tutorials/how-to/reference/explanation)
• Readme Driven Development — write README first

Review contract

Axes: the section check (2a.1) and the anti-pattern scan (2a.2). The block below closes the Step 2a report.

The review ends here, in this shape. A review with no output section has not run.

Judge primary evidence. The diff, the file, the EXPLAIN output, the rendered page — never your own summary of the change, and never your memory of what you meant to write. Resolve the base first, then cover committed, staged, unstaged and untracked changes. Read untracked files in full: diff output omits them.

Every axis reports. Each axis produces at least one finding, or one line saying what it inspected and what that evidence does not prove. An axis that says nothing has not looked.

Report what you inspected. "No findings in the two files I opened" and "no findings in the change" are different claims, and only the first one is ever true.

Copy code
Inspected:     <files, queries, URLs, viewports actually opened>
Not inspected: <in scope, not examined, and why>
Findings:      <n blocking, n concerns>
Verdict:       BLOCK | CONCERNS | CLEAN

• BLOCK — at least one finding that, shipped as written, risks data loss, a security or privacy breach, a production incident, or a wrong answer to a user.
• CONCERNS — no blocking finding, but at least one a maintainer should fix or answer first.
• CLEAN — every axis inspected against primary evidence, nothing at either bar. CLEAN claims only the axes above and the files on the Inspected line, and it is wrong if a defect is later found in them.

Not a review: LGTM; restating what the change does; cosmetic findings only; reading the changed lines without the code they call.