README Writer

Creates a factual, developer-ready README.md. Gathers information exclusively from verified repository manifests and commands—never inventing imaginary features or unverified flags.

1. Purpose

Provide newcomers with a clean, truthful overview of a codebase. A "README" covers project goal, prerequisites, quickstart installation, basic usage, and test commands.

2. When to Use

Use this skill when:

• Creating a new project or open-source repository.
• Overhauling a missing or outdated README.md.
• User asks: "Generate a README for this repository."

3. When Not to Use

• Do not use to write a narrative walkthrough tutorial; use step-by-step-tutorial.
• Do not use to map codebase internals without writing docs; use repo-inspector.

4. Required Inputs

• project_name: Name of the project (string).
• workspace_root: Directory of the project to inspect for package manifests.
• description: 1-2 sentences on what the project does.

5. Missing-Input Behavior

1. If commands (install, test, build) are not provided: inspect package.json, Cargo.toml, pyproject.toml, or Makefile in workspace_root.
2. Do not document CLI flags or options that cannot be verified in the source code.
3. If license is unknown, check LICENSE file on disk before specifying.

6. Procedure

Follow these numbered actions:

1. Action 1: Verify Stack & Prerequisites
   • Identify required runtime (Node.js, Python, Rust, Go) and minimum version from manifests.
2. Action 2: Verify Key Commands
   • Confirm install command (npm install), build command (npm run build), and test command (npm test).
3. Action 3: Structure Standard Sections
   • Title & description.
   • Prerequisites.
   • Quickstart (Installation & Usage).
   • Running Tests.
   • Contributing & License.
4. Action 4: Emit Markdown Document
   • Format using Section 8.

7. Decision Rules

• If no test command exists: omit "Running Tests" or write No automated tests configured. Do not invent a command.
• Keep total length concise (< 500 lines); link to subdocuments for detailed manuals.

8. Output Format

Emit the README content using this template:

# [Project Name]

[Short, clear summary of what the project does in 1-2 paragraphs.]

## Features
- [Verified Feature 1]
- [Verified Feature 2]

## Prerequisites
- [Runtime and version, e.g. Node.js >= 20.0.0]
- [Package manager, e.g. npm or pnpm]

## Installation
```bash
[Verified installation command]

Quickstart / Usage

[Verified minimal usage command or code snippet]

Running Tests

[Verified test command]

License

[License type, e.g. MIT - see LICENSE file]

## 9. Verification Checklist
- [ ] Every listed command exists in project configuration.
- [ ] Prerequisites match actual engine/runtime constraints.
- [ ] No fake badges, fake metrics, or ungrounded claims.
- [ ] Code examples are syntactically complete.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Hallucinating CLI flags | Assuming common flags exist | Run `<bin> --help` or check source code parser. |
| Inaccurate prerequisites | Guessing version | Read `package.json -> engines` or `.nvmrc` / `runtime.txt`. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- Project purpose cannot be deduced from repository files.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Project: logger-lite
Stack: Node.js, package.json scripts: { "test": "mocha tests" }
Description: Zero-dependency JSON logger for microservices.

Output:

# logger-lite

Zero-dependency JSON logger for microservices. Formats structured logs with timestamp, log level, and process ID.

## Features
- Zero external dependencies.
- Automatic ISO-8601 timestamps.
- NDJSON output for log ingestion pipelines.

## Prerequisites
- Node.js >= 18.0.0
- npm

## Installation
```bash
npm install logger-lite

Quickstart

const { Logger } = require('logger-lite');
const log = new Logger();

log.info('Application started', { port: 8080 });

Running Tests

npm test

License

MIT

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Write README for unknown project in empty folder.

Output:

### README Writer: Halted - No Project Data

- **Status**: Halted

Cannot generate an accurate README for an empty workspace. Please provide:
1. The project name and purpose.
2. The programming language / runtime.
3. The expected build and test commands.

Example 3: Expected Final Output

Output:

# csv-cleaner

Fast CLI utility to clean trailing spaces and normalize delimiters in CSV files.

## Prerequisites
- Python >= 3.10

## Installation
```bash
pip install -e .

Usage

csv-cleaner input.csv --output clean.csv

Running Tests

pytest tests/

License

MIT