Skip to content

docs: point the contributor checklists at docs that exist (BEA-191) - #201

Open
ssowonny wants to merge 1 commit into
mainfrom
bea-191-ph-scan-bug-contributingmd-and-the-pr-template-both-require
Open

ssowonny wants to merge 1 commit into
mainfrom
bea-191-ph-scan-bug-contributingmd-and-the-pr-template-both-require

Conversation

@ssowonny

@ssowonny ssowonny commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

TL;DR

  • Every PR here shipped with a checkbox nobody could tick.
  • The template and CONTRIBUTING.md both demanded you update plugin/skills/beardrive/SKILL.md — a file deleted on purpose, in a plugin/ directory that doesn't exist.
  • An untickable box trains people to tick without reading, which quietly devalues the three real boxes above it.
  • Both lines now name the surfaces CLAUDE.md's own "Docs to keep in sync" section lists.
  • Docs only. Two lines, no code, no new paths that don't exist.

The change

One substitution, applied in the two places the stale path survived:

  .github/PULL_REQUEST_TEMPLATE.md:10
- - [ ] CLI behavior changes updated both `README.md` and `plugin/skills/beardrive/SKILL.md`
+ - [ ] CLI behavior changes updated `README.md`, `INSTALL_FOR_AGENTS.md` and `web/docs/src/content/docs/`

  CONTRIBUTING.md:49-52
  - **Docs travel with behavior.** Changing CLI commands, flags, or output
-   means updating both `README.md` and `plugin/skills/beardrive/SKILL.md`
-   — the skill is what makes agents beardrive-aware and must match the
-   binary.
+   means updating `README.md`, `INSTALL_FOR_AGENTS.md`, and
+   `web/docs/src/content/docs/` — `INSTALL_FOR_AGENTS.md` is the runbook
+   agents follow to set themselves up, and `web/docs` is the end-user
+   reference published at docs.beardrive.ai.

The CONTRIBUTING justification clause goes with the path. "The skill is what makes agents beardrive-aware and must match the binary" described nothing that exists — the agent integration is internal/agenthooks plus INSTALL_FOR_AGENTS.md, which is what CLAUDE.md says too.

Why these three surfaces

They aren't a judgment call. CLAUDE.md's "Docs to keep in sync" section already names exactly them, so the edit is a substitution rather than an invention:

surface what goes stale in it
README.md flags, output formats, on-disk layout
INSTALL_FOR_AGENTS.md the init / login / hooks flow agents follow
web/docs/src/content/docs/ reference/cli.md, reference/hub-config.md, reference/project-files.md, self-hosting/

web/docs/src/content/docs/ is a directory, not a file. Naming the directory keeps the checkbox tickable in ten seconds; naming its four stale-prone pages would have turned one box into five, which is the problem this PR is fixing.

What was checked

  • git grep -n "plugin/skills" → no output. Those two lines were the only references repo-wide; nothing else pointed at the deleted tree.
  • ls README.md INSTALL_FOR_AGENTS.md web/docs/src/content/docs/ → all three exist.
  • PR template checkbox count and ordering unchanged: 4 before, 4 after.
  • go build ./... && go vet ./... green. go test ./... green (see below) — no .go or frontend file is touched by this diff, so no npm run build, no static/ rebuild, no e2e, and no new test to add.
  • Touches no package drawn in architecture/, so no diagram section.

What this doesn't do

The scope was deliberately two lines. It does not audit other stale paths elsewhere in the repo, restore a plugin/ directory, or rewrite the rest of either file. If more corpses are pointed at from contributor-facing docs, they'd need their own sweep — this PR only proves there are no others named plugin/skills.

Closes BEA-191.

Build session

cd $(git worktree list | grep infallible-kepler-9df580 | awk '{print $1}') && claude --resume 44ad41c1-c6fa-4bc2-b442-ef64a1814aa0

(Only works on the machine this branch was built on.)

The PR template and CONTRIBUTING both required updating
`plugin/skills/beardrive/SKILL.md` on a CLI behavior change. That tree
was deleted deliberately — CLAUDE.md states there is no Claude Code
plugin and no bundled skill — so every PR carried a checkbox nobody
could tick, which trains contributors to tick without reading.

Both now name the three surfaces CLAUDE.md's own "Docs to keep in sync"
section lists: README.md, INSTALL_FOR_AGENTS.md, and
web/docs/src/content/docs/. The CONTRIBUTING justification clause about
the skill making agents beardrive-aware goes with it — it described
nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant