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:

   - 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:

   # 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 }.