/readme

Why this package

Explain why the project exists and help the reader decide whether its purpose fits their problem. A human origin story can carry that explanation. It need not read like a competitor comparison. An origin story still needs ecosystem context: what already exists and why the author chose to build this project. Keep that context brief and connected to the story. A feature matrix is optional.

Find the story

Read supplied author notes, existing prose, and documented origins before drafting. Look for the concrete frustration, the response, and the purpose that connects them. Use those details to explain why someone bothered to build this particular project. Preserve supplied first-person experience and distinctive voice when they serve the story. Never invent feelings, anecdotes, dialogue, dates, or a sequence of events to make the story engaging. Repository history supports what changed. It does not establish how the author felt or why they made each decision. If the origin is unknown, use a concrete reader situation without presenting it as the author's experience. Ask for missing personal context only when the requested story depends on it. Keep comparisons and measured evidence beside the claims they support, or link to them from Features or Guides. Do not turn the opening into a feature inventory or an evaluation report.

Establish the comparison

Read supplied positioning, requirements, decision records, and examples before asking the owner. Preserve the owner's chosen audience. Concrete examples do not require narrowing the whole project to that audience. If a collection serves writing for people and agents, explain both tasks using its supported skills. Identify the reader's task, current workaround, and the cost or missing outcome that matters to them. Inspect relevant competing packages and the default approach without this package. For internal software, inspect the team's existing process, integrations, and required business rules. Bespoke fit can be the adoption reason. Do not force an internal tool into a public competitor comparison. Use current official documentation, source, and published results for material claims. Record the source revision and comparison scope in private working evidence. Compare the same task and dimensions across alternatives. Do not compare a whole collection with one narrow skill as peers.

Find the concrete gap, the package's supported response, and the resulting reader benefit. Distinguish shared features from differentiators. A useful combination can differentiate a package when individual features are common. For agent skills, standard description-based selection and portable folders are shared format features. They explain usage, but they do not establish uniqueness.

Decide whether to interview

For competitive positioning, confidence requires a reader, a relevant alternative, an adoption reason, and evidence of its benefit. For an origin story, use documented origins or supplied experience and a clear connection to the reader's problem. Establish the supported reason for building alongside existing options, even when the reason is personal fit or a useful combination. Do not infer that the author tried, rejected, or outperformed an alternative from its existence. Do not require a competitive advantage or a marketing interview before telling a supported story. Use the evidence already supplied when these are clear. Do not interview merely because the project lacks an exclusive feature. If the missing intent would materially change Why, ask one direct question before finalizing that section:

Why would someone use this over existing solutions?

Name the relevant alternatives and give the researched hypothesis so the owner need not repeat known context. For bespoke software, adapt the question to its actual decision:

What does this do for your team that your current tools or process do not?

Ask a targeted follow-up only if the answer leaves a material ambiguity. Do not start a broad marketing questionnaire or make the owner summarize inspected code. Continue independent setup, inventory, and documentation work while waiting. An owner answer establishes intent. Verify technical and comparative claims against evidence before publishing them. If the owner does not answer, keep the proposed USP in the handoff and use only supported facts in the README. Do not turn an unanswered hypothesis into an established adoption reason.

Write the adoption case

Lead with the supported origin or the reader's problem, according to the requested emphasis. Connect it to the project's purpose. Use research to support technical and comparative claims. Keep the opening brief. Put mechanisms, feature lists, competitor walkthroughs, and evaluation methods in their relevant sections. If the owner requests problem-only positioning, lead with the failure and omit implementation detail and capability lists. Before trimming, identify the approved problems, adoption reasons, audience, qualifications, and evidence links. Map each point to retained wording or a useful destination. Remove a point only when the requested scope excludes it. An instruction to remove generic prose does not authorize dropping supported facts, comparisons, or approved positioning. Support the adoption reason with inspected behavior, a working example, or measured evidence in the research record. Name competitors only when the comparison helps the reader choose. Link sources beside published comparative claims. Keep scope clear: an observed gap in inspected alternatives does not prove absence across the entire market. Claim broader evaluation coverage only when comparable cases and dimensions establish it. When publishing measured results, link their evidence and preserve their limits. A pilot alone does not establish overall superiority.

State consequential trade-offs and cases where an alternative fits better when they affect adoption. Do not invent a competitive gap, unsupported quality ranking, or "only" claim to fill the section. If evidence supports a fit but no exclusive feature, explain the supported fit and combination. Keep research commentary outside the published README.

Review Why

Ask what each sentence adds: the origin, the problem, its cost, the project's purpose, or supporting evidence. Read the opening as a whole. Does it explain why the project exists through a connected story? Can the reader see the relevant existing options and why this project was built alongside them? Keep the author's choice distinct from comparative claims about what other projects cannot do. Preserve grounded personal details even when they do not establish a competitive advantage. If another unrelated project could use the sentence unchanged, cut it or identify the actual failure. Use this as a review question. Do not automatically delete approved positioning or evidence links because they share ordinary wording. Shared format properties and routine repository practices do not establish an adoption reason. Do not invent an exclusive problem or a superiority claim when the evidence supports only a particular fit. Keep necessary qualifications beside any claim they limit. Remove the whole claim when it does not belong here.

Use supplied copy rules for sentence-level bans and the glossary for product-name bans. Follow each ban's scope and replacement. Do not ban a live product name, command, or identifier as generic language. If no wording guide exists, use these review questions without inventing one or requiring a personal skill.