---
name: audit-readme
description: Use when the user says "audit my README" / "what's missing from the README" / "rewrite the README lede" — fetches the repo's README.md via a Composio-connected code host (or accepts a paste), scores it against a standard checklist (one-sentence pitch, badges, quickstart, install, usage, configuration, contribution, license), and writes an audit with inline diff suggestions, a rewritten lede, and a prioritized fix list. Draft only — never auto-commits.
---

# Audit README

## When to use

- User: "audit my README" / "what's missing from our README" / "score
  my README" / "rewrite the README lede".
- Implicit trigger: a new repo slug is mentioned + no prior
  `readme-audits/{repo-slug}.md` exists.
- Rerun anytime the README is updated — a fresh audit lands under a
  new filename or overwrites the existing one (user preference).

## Steps

1. **Read engineering context.** Open
   `../head-of-engineering/engineering-context.md`. If missing or
   empty, stop and tell the user:
   > "I need the engineering context doc before I can audit your
   > README well — it tells me stack, positioning, and quality bar.
   > Run the Head of Engineering's `define-engineering-context`
   > first."

2. **Read config.** Read `config/docs-home.json` and
   `config/doc-audience.md`. These shape tone expectations and
   whether a deep README is load-bearing (README-only projects) or a
   starter pointer (docs-site projects).

3. **Resolve the repo + fetch README.**
   - If the user named a repo (e.g. `owner/repo` or a GitHub URL),
     run `composio search code-hosting` to find the connected tool,
     then fetch `README.md` from the default branch.
     - If no code-hosting tool is connected, tell the user which
       category to link and stop. Offer: "…or paste the README
       contents and I'll audit what you give me."
   - If the user pasted README content, use it as-is.
   - If ambiguous, ask ONE question: "Which repo? (Paste the URL or
     name — or drop the README contents directly.)"
   - Save resolved `{ owner, repo, defaultBranch }` to
     `config/repo.json` for future skills.

4. **Score against the standard checklist.** For each section, label
   `present` / `missing` / `weak` and (if weak or missing) write a
   one-line reason. The checklist:

   | Section | What good looks like |
   |---|---|
   | One-sentence pitch | Top of file, under H1. Answers "what is this, who's it for" in under 25 words. |
   | Badges | Build status + package version + license. Optional: coverage, docs. |
   | Quickstart | 3-5 commands that get a reader to a running app or a hello-world call. |
   | Install | Exact install command(s) per supported package manager / platform. |
   | Usage | Minimal code example that actually runs against the current API. |
   | Configuration | Required env vars + default config + a note on where secrets go. |
   | Contribution | Link to CONTRIBUTING.md or inline: branch naming, PR template, run-tests command. |
   | License | Explicit license name + link to LICENSE file. |
   | Repo map (optional) | For non-trivial layouts: 5-10 line "where to find what". |
   | Links (optional) | Docs site, changelog, discord/slack. |

5. **Write a rewritten lede.** One sentence, ≤ 25 words, grounded in
   the engineering context doc's product description + target
   audience. Example: "`postgres-lite` is an embeddable, single-file
   Postgres replacement for CLI tools and local dev, without a running
   server." If unknown, mark UNKNOWN and ask.

6. **Write inline diff suggestions.** For each weak / missing
   section, propose the exact replacement block as a fenced markdown
   diff:
   ```diff
   - Old content (or absent)
   + Proposed content
   ```
   Never invent commands the repo doesn't support — cite the source
   (package.json script name, Makefile target) or mark UNKNOWN.

7. **Build the prioritized fix list.** Top-3 first, labeled by
   impact: `[P0]` blocks understanding (no pitch, no install), `[P1]`
   blocks usage (no example, no config), `[P2]` hygiene (license,
   badges, contrib). 3-10 total items.

8. **Write** to `readme-audits/{repo-slug}.md` atomically
   (`*.tmp` → rename). File structure:
   ```markdown
   # README Audit — {owner}/{repo}

   **Audited:** {ISO date}
   **Branch:** {default branch}
   **Size:** {N} words / {M} sections

   ---

   ## Proposed lede

   > {one-sentence rewrite}

   ## Checklist

   | Section | Status | Notes |
   |---|---|---|
   | One-sentence pitch | missing | — |
   | Badges | weak | only build status |
   | ... | ... | ... |

   ## Suggested diffs

   ### Pitch
   ```diff
   + {one-line pitch}
   ```

   ### Install
   ...

   ## Prioritized fix list

   1. **[P0]** Add a one-sentence pitch under the H1. (Est. 2 min)
   2. **[P0]** Add an install command block. (Est. 2 min)
   3. **[P1]** ...
   ```

9. **Append to `outputs.json`** — read existing array, add new entry
   (`id` uuid v4, `type: "readme-audit"`, `title: "README audit —
   {owner}/{repo}"`, `summary: "{N} missing / {M} weak sections;
   top fix: {P0 item}"`, `path: "readme-audits/{repo-slug}.md"`,
   `status: "draft"`, timestamps), write atomically.

10. **Summarize to user** — one paragraph: what's missing / weak,
    the proposed lede, the top-3 fixes, and the path to the audit.
    End with: "Edit your README.md in the repo, commit when you're
    happy. I never push."

## Hard nos

- Never invent commands or configuration the repo doesn't support —
  cite the source or mark UNKNOWN.
- Never push a fixed README back to the repo. Output is a draft at
  `readme-audits/{repo-slug}.md`.
- Never audit without reading `engineering-context.md` first.

## Outputs

- `readme-audits/{repo-slug}.md`
- Appends to `outputs.json` with `{ id, type: "readme-audit", title,
  summary, path, status: "draft", createdAt, updatedAt }`.