Add the required README sections (Getting Started, Rationale, Design, Author) #75

New Issue

clawbot · 2026-08-09T03:42:19+02:00

clawbot commented

2026-08-09 03:42:19 +02:00

Context

Policy names the required README sections. Five divergences:

Description first line omits the author. README.md:3-6 gives name,
category, and license but not the author. The required shape is "X is an
MIT-licensed Go web application by @sneak that...".
No Getting Started section. There is no heading by that name
anywhere and no copy-pasteable install/usage block. A reader currently
has no way to install or run the tool without reading the Makefile.
No Rationale heading. The content exists, spread across "Problem
Statement" and "Proposed Solution" (README.md:80-135), but not under
the required name.
No Design section. # Design Goals (README.md:137-144) covers
product goals, not "how is the program structured". Nothing documents the
mfer/ library vs internal/cli/ vs cmd/mfer/ split.
# Authors should be # Author, with the canonical
[@sneak](https://sneak.berlin) link form.

Definition of done

The first line of the README names the project, purpose, category,
license, and author, matching the policy template.
A # Getting Started section exists with a copy-pasteable block covering
install and basic usage (mfer gen, mfer check, mfer fetch).
A # Rationale section exists. Existing Problem Statement / Proposed
Solution content is consolidated under it rather than duplicated.
A # Design section exists describing the package layout: mfer/ as the
reusable library, internal/cli/ as the command implementations,
internal/log/ and internal/bork/ as support, cmd/mfer/ as the
entrypoint, and where the generated protobuf code sits.
The # Authors heading is renamed # Author and uses the canonical link.
All commands shown in Getting Started are verified to actually work
against a built binary before the PR is opened.
make check passes. TODO.md updated in the same commit.

Implementation requirements

Verify every command you put in the README by running it. A Getting
Started block that has not been executed is worse than none.
The install instruction must be correct for the module path as it actually
is today. Note the module path is unsettled (#79) — do not pre-emptively
document a path that is not yet real; document what works now, and #79
will update it when the decision lands.
Do not delete the existing Problem Statement / Proposed Solution prose
wholesale. Restructure and keep the substance; the author wrote it
deliberately.
Do not touch the # TODO: Remaining Work for 1.0 section in this PR — it
is stale and is being rewritten separately in #76. Two PRs editing the
same large section will conflict.
Run make fmt so the markdown is formatted with the repo's own settings
before committing.
Commit title must end with (closes #75).

## Context Policy names the required README sections. Five divergences: 1. **Description first line omits the author.** `README.md:3-6` gives name, category, and license but not the author. The required shape is "X is an MIT-licensed Go web application **by @sneak** that...". 2. **No `Getting Started` section.** There is no heading by that name anywhere and no copy-pasteable install/usage block. A reader currently has no way to install or run the tool without reading the Makefile. 3. **No `Rationale` heading.** The content exists, spread across "Problem Statement" and "Proposed Solution" (`README.md:80-135`), but not under the required name. 4. **No `Design` section.** `# Design Goals` (`README.md:137-144`) covers product goals, not "how is the program structured". Nothing documents the `mfer/` library vs `internal/cli/` vs `cmd/mfer/` split. 5. **`# Authors` should be `# Author`**, with the canonical `[@sneak](https://sneak.berlin)` link form. ## Definition of done - The first line of the README names the project, purpose, category, license, and author, matching the policy template. - A `# Getting Started` section exists with a copy-pasteable block covering install and basic usage (`mfer gen`, `mfer check`, `mfer fetch`). - A `# Rationale` section exists. Existing Problem Statement / Proposed Solution content is consolidated under it rather than duplicated. - A `# Design` section exists describing the package layout: `mfer/` as the reusable library, `internal/cli/` as the command implementations, `internal/log/` and `internal/bork/` as support, `cmd/mfer/` as the entrypoint, and where the generated protobuf code sits. - The `# Authors` heading is renamed `# Author` and uses the canonical link. - All commands shown in Getting Started are verified to actually work against a built binary before the PR is opened. - `make check` passes. `TODO.md` updated in the same commit. ## Implementation requirements - Verify every command you put in the README by running it. A Getting Started block that has not been executed is worse than none. - The install instruction must be correct for the module path as it actually is today. Note the module path is unsettled (#79) — do not pre-emptively document a path that is not yet real; document what works now, and #79 will update it when the decision lands. - Do not delete the existing Problem Statement / Proposed Solution prose wholesale. Restructure and keep the substance; the author wrote it deliberately. - Do not touch the `# TODO: Remaining Work for 1.0` section in this PR — it is stale and is being rewritten separately in #76. Two PRs editing the same large section will conflict. - Run `make fmt` so the markdown is formatted with the repo's own settings before committing. - Commit title must end with ` (closes #75)`.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:42:19 +02:00

clawbot referenced this issue

2026-08-09 03:43:25 +02:00

DECISION: canonical Go module path for 1.0 #79

clawbot referenced this issue

2026-08-09 03:44:35 +02:00

DECISION: public API surface and determinism defaults for 1.0 #83

clawbot referenced this issue

2026-08-09 03:45:49 +02:00

Stale branch cleanup: three unmerged branches, none worth keeping as-is #85

Sign in to join this conversation.