Proposal: ce-docs-audit — keep a repo's entry-point docs true (README, AGENTS.md, CLAUDE.md)
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 28/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức độ hoạt động
- Ít trao đổi
- Công nghệ
- python
- Lĩnh vực
- developer-experience, documentation, tooling
Hướng nghiên cứu
Start by reading the existing ce-compound, ce-compound-refresh, ce-doc-review, and ce-handoff skills plus issue #866, then inspect validate-doc-claims.py for reusable claim checking. Use README.md, AGENTS.md, and CLAUDE.md in test repositories to define the audit checks and safe command policy. Done means maintainers have chosen the skill boundary and agreed how reporting, consent, and --report-only mode should work before implementation under tests/ and docs/skills/ begins.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
The gap
The plugin compounds knowledge about problems exceptionally well. It has no
skill that maintains the front door — README.md, AGENTS.md, CLAUDE.md —
against the current tree.
I checked the existing skills before writing this, and each is adjacent rather
than overlapping:
| Skill | Surface | Why it does not cover this |
|---|---|---|
ce-compound |
docs/solutions/ |
Captures one solved problem. Its Discoverability Check does touch AGENTS.md, but only to add a pointer to the knowledge store — it never checks whether anything already in those files is still true |
ce-compound-refresh |
docs/solutions/ |
Refreshes solution docs for staleness. Same idea, different surface |
ce-doc-review |
A requirements or plan document | A document under construction, reviewed with role lenses. Entry-point docs are shipped artifacts with different failure modes |
ce-handoff |
Session context | Ephemeral by design, and correctly so. This is about what belongs in the repo permanently |
ce-explain |
A teaching artifact | Explicitly "for learning, not repo docs or verdicts" |
So the gap is real and narrow: nobody audits the docs a newcomer actually reads
first.
Why it matters, with the case that prompted it
Entry-point docs rot differently from other docs, because the people who would
notice already know the answers. The cost lands entirely on the next person.
Yesterday I finished a week-long spike and wrote its README carefully. It contained
this setup step:
sprite file push -s <name> sprite/bootstrap.sh /tmp/bootstrap.sh
The second time I provisioned a machine, that command failed: a fresh Fly Sprite
has no /tmp, and the CLI refuses the path with directory /tmp does not exist
even though ls shows the directory. My own setup instructions were wrong, in a
document I had written two hours earlier, and no existing skill would have caught
it — because it is not a stale reference or a missing section, it is a claim
about the world that only fails when someone follows it.
That is the highest-value check this skill would run, and I have not seen it
anywhere: treat every command in the docs as an assertion, and verify the ones
you safely can.
Proposed shape
Four checks, all reported even when they pass, because a silent pass is
indistinguishable from a skipped check.
1. Executable claims. Extract every command from the entry-point docs. Run the
cheap, safe, side-effect-free ones (--help, --version, --dry-run,
typechecks). For the rest, verify statically — does the referenced file exist, does
the flag appear in --help, does the script name exist in package.json — and say
plainly which could not be verified rather than implying they passed. A failing
command is the most valuable output.
2. State. Do the docs say what is deployed, what is half-done, and what to pick
up first with why it matters? State drifts faster than anything else in a README,
so check it against recent commits, open PRs, and whether the "coming soon" thing
shipped months ago.
3. Load-bearing decisions. Which decisions would a competent newcomer undo,
reasonably, and be wrong? The retry that looks paranoid, the async hop that could
obviously be an await, the function that looks dead. Then check whether the
reason is written where the person about to undo it would look. A reason that
lives only in a commit message is not documented — nobody reads git log before
refactoring. This is the strongest argument for a repo having an AGENTS.md at
all, so proposing one is a legitimate finding.
4. Orientation. Is there a plain first sentence, a stated reading order, and do
the entry-point files point at each other rather than each assuming it is the only
one read? If both AGENTS.md and CLAUDE.md exist, is one a pointer rather than a
second copy that will drift?
Design choices worth arguing about before any code
- Report before editing, and lead with what is wrong rather than what is
missing. A broken command outranks an absent section. Absence is easy to see
and easy to fix; the newcomer who hits a failing setup command in the first five
minutes never reaches the missing section. - Smallest edit, never a rewrite. The job is a true front door, not a good
one. A rewrite loses the author's voice, invites review nobody asked for, and
buries the two lines that mattered. - Blocking consent before touching entry-point docs, matching
ce-compound's treatment of instruction files. These are the repo's public face
and frequently reviewed. --report-onlyfor CI, which is where I would expect most of the value over
time: catch a broken setup command on the PR that broke it.
Relationship to #866
#866
(promote durable lessons onto enforced surfaces) is the closest existing issue and
it is solving a different half of the same problem, so worth naming rather than
letting a maintainer spot the overlap.
- #866 asks whether a lesson is enforced. Its concern is that a captured lesson
stays retrieval-dependent - it only changes behaviour if an agent happens to
read it. - This asks whether what is written is still true. Its concern is a document
that is read, confidently, and is wrong.
They compose rather than compete. Check 3 below - are load-bearing decisions
documented where someone about to undo them would look - is the weaker,
verification-side cousin of #866's promotion ladder. If #866 lands, this skill is
what later catches the moment a promoted rule stops matching the tree.
Open questions for maintainers
- Is this a skill or a phase of an existing one? A case exists for folding it
intoce-compound-refreshas a second surface — it is the same "verify against
the tree" motion. I lean separate, because the trigger is different (handing
over or onboarding, not documenting a learning) and because--report-onlyin
CI wants its own entry point. Happy to be wrong. - How far should command execution go? Running commands from a document is
real risk. My instinct is a conservative allowlist — no writes, no network
mutations, no deploys — and static verification for everything else. There may
be an existing convention in the repo I should follow instead. - Naming.
ce-docs-auditreads clearly;ce-docsis terser but sounds like
it generates docs, which is the opposite of what it does. - Overlap to resolve deliberately:
ce-compound's Discoverability Check also
editsAGENTS.md. If both exist, one of them should own instruction-file edits.
I would give it to this skill and havece-compoundkeep only its pointer
insertion, but that is a maintainer call.
I ran it, and it caught this
Not a design sketch. I built the local version, then pointed it at the same
repository whose docs I had written the previous day, and it found four false
commands out of nine.
Executable claims: 9 checked, 4 fail
FAIL sprite file push -s <name> sprite/bootstrap.sh /tmp/bootstrap.sh
FAIL sprite file push -s <name> sprite/agent-server.mjs /tmp/agent-server.mjs
FAIL sprite exec -s <name> --env GITHUB_TOKEN=... -- bash /tmp/bootstrap.sh
Error: directory /tmp does not exist
FAIL cd worker && npm install && npx wrangler deploy
Wrangler requires at least Node.js v22.0.0. You are using v20.20.0.
The other three checks passed - the state section was current, all five
load-bearing decisions were documented with the cost of reverting them, and the
reading order was clear. Thirteen of thirteen referenced files and doc links
resolved.
The cause is the argument for the skill. AGENTS.md in that same repository
recorded the /tmp trap correctly, on the same day, in a section literally titled
"three things that will waste your time otherwise". The README still told you to do
the broken thing. Two documents, one truth, and nothing keeping them agreed.
The Node 22 failure has the same shape: the constraint was written in one file and
the command that violates it was in the other.
Neither is a stale link, a missing section, or a dead reference - the classes of
problem existing tooling finds. Both are commands that only fail when a newcomer
runs them, which is exactly when it is most expensive.
What I have already
A working local version, used on two repositories, and the concrete case above. If
this is worth having I am happy to do the work to the repo's standards — tests
under tests/, a doc under docs/skills/, the headless/lightweight mode split,
and the validate-doc-claims.py mechanical check reused rather than reimplemented.
If the answer is "fold it into ce-compound-refresh" or "not for this plugin",
that is a useful answer too and I would rather hear it before writing anything.
- Ngôn ngữ chính
- TypeScript
- Star
- 25.6k
- Fork
- 2.1k
- Merge trung bình
- 3 giờ 57 phút
- Pull request đã merge (30 ngày)
- 170
Chuẩn bị môi trường
Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của EveryInc/compound-engineering-plugin
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
EveryInc/compound-engineering-plugin#2085 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 66/100
EveryInc/compound-engineering-plugin#795 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 80/100
EveryInc/compound-engineering-plugin#2084 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 48/100
EveryInc/compound-engineering-plugin#2083 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Host support: DeepSeek Harness (dsh)Có thể đã có người làm Có pull request liên kết đang mở hoặc đã được merge. Đang mở
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 48/100
EveryInc/compound-engineering-plugin#2072 ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của EveryInc/compound-engineering-plugin
Issue tương tự
-
bug impact:low Team: SecuritySolution Team:Defend Workflows v9.6.0
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
elastic/kibana#306401 · 3 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
agentes-chat/agentes-chat#927 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
[Bug]: Webapp workspace fails to render in Safari — "Can't find variable: requestIdleCallback"Đang mởcomp/desktop P2 type/bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
NousResearch/hermes-agent#157702 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
Maintainer thường phản hồi trong vòng 1 ngày
-
e2e-failure ready-to-code
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 72/100
redhat-developer/rhdh-plugin-export-overlays#4794 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày