Periodic judgment sweep for doc drift a check can't catch (files issues, no edits)

Open
  • Is something wrong?
#7,628 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
devtools, documentation

Research direction

Read #7624 and #7617 first to understand the existing audit and parallel read-only approach. Compare the procedures in .claude/skills, .claude/rules, .claude/agents and docs/agents with the workflows and tools, then check README and docs/validation.md claims against cited evidence and dates. Document the doc groups, comparison list, and issue format in a skill or docs/agents/ page; done when the first run files findings with both sides and file:line references.

Written by the indexing model from the issue text.

Description

documentation

Part of #7624 (step 5).

About 20% of the drift in #7617 needed judgment no check can supply:

  • CLAUDE.md still described a removed PR trigger on the full-suite matrix (#4518).
  • Three skills told agents to call update_golden_master.py directly, against golden-master-guidelines.md.
  • The tri-comparison figures (200/201, 2026-08-30) had not been re-audited.
  • Procedures conflicted: a rebase with --force-with-lease vs. "never rebase".

Change: a monthly sweep, or one before each release tag, by an agent run. It compares:

  1. procedures in .claude/skills, .claude/rules, .claude/agents and docs/agents against the workflows and tools they describe (triggers, required steps, the bless path);
  2. README and docs/validation.md claims against their cited evidence, with dates;
  3. contradictions between docs.

It files issues and never edits files, because most of these fixes need an owner decision. Each issue names both sides, with file:line references. Parallel read-only agents, one per doc group, as in #7617, keep the cost down; the doc-refs audit has already removed the mechanical half.

Acceptance: a documented runbook (a skill or a docs/agents/ page) with the doc groups, the comparison list and the issue format. The first run files its findings.

Dominant language
Python
Stars
57
Forks
11
Avg merge
1h 35m
Merged PRs (30d)
975

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from squid-protocol/gitgalaxy

All issues in squid-protocol/gitgalaxy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.