docs: refresh stale documentation and remove dead submission path - #372
Merged
Conversation
The README's category counts and the documented CLAUDE_MODEL default had drifted from the repo. Embers and Alchemy were off by roughly 2x, and the model ID disagreed in three places after 2a76552 migrated the scripts to Sonnet 5 without updating the docs or the site copy. Counts (README): library total 130+ -> 300+, Flames 100+ -> 250+, Embers 17 -> 30+, Alchemy 14 -> 25+, contributors badge 29+ -> 38+. Actual figures are 320 / 259 / 34 / 27 / 38; rounded "N+" keeps the existing convention and avoids re-staling on every merge. Model ID: README, docs/TESTING_GUIDE.md, and home.html now all say claude-sonnet-5, matching process_hunt_submission.py, generate_from_cti.py, and duplicate_detection.py. home.html had claude-sonnet-4-6, which is not a real model ID and was user-facing on the site. The prettier hook also normalized pre-existing formatting drift in both markdown files (table padding, *italic* -> _italic_, blank lines before lists). Only nine lines are semantic; the rest is formatting. Verified: npm run type-check clean, npm test 11/11 passing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
scripts/README.md had not been updated since 2025-06-25 and described a codebase that no longer exists. It documented five scripts, of which parse_hunts.py and test_runner.py are gone, along with config_manager.py, logger_config.py, validators.py, and a hearth_config.json config file — none of which are in the repo. Eighteen of the twenty-two current scripts were undocumented, including the entire CTI pipeline. Rewritten around what the scripts actually do, grouped by role (generation pipeline, hunt-ID integrity, parsing/schema, site data builders) with a "Run by" column mapping each script to the workflow that invokes it, since almost nothing here is run by hand. docs/TESTING_GUIDE.md predated scripts/tests/ entirely and never mentioned pytest. Adds an Automated Test Suite section up front covering all seven test files, the fixtures layout, and the fact that CI does not run them. Replaces the "Automated Testing (Future)" checklist, which listed as planned two things that now exist. Also fixes a broken command: the guide told you to run scripts/test_database_speed.py, which does not exist. Replaced with a runnable index-currency check, since a stale index is the failure mode that actually affects duplicate detection. Notes that database/hunts.db is gitignored, so local drift is expected and CI rebuilds it on merge. Every command in both documents was executed before committing; every script and workflow path was checked to resolve. Not addressed here, flagged for follow-up: .github/workflows/ process-manual-issue.yml still invokes scripts/process_manual_submission.py, deleted in 0b408cb (2025-06-21). That workflow fails whenever the manual-submission label is applied. Verified: pytest 70/70, npm run type-check clean, npm test 11/11. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Corrects an error introduced in ddbe639. That commit stated in two places that CI does not run the pytest suite. It does: validate-hunt-schema.yml runs `pytest scripts/tests/ -v` on every pull request, deliberately with no path filter so it can serve as a required status check. The earlier claim came from inspecting ci.yml alone. Both scripts/README.md and docs/TESTING_GUIDE.md now describe the split accurately — hunt validation plus pytest in validate-hunt-schema.yml, Node build and flake8 in ci.yml. Keepers/Review-Process.md was a five-line TODO stub that had never been written. Now documents the label-driven pipeline (intel-submission, submission, regenerate, approved), which automated checks run and when, what reviewers should actually assess per hunt category, and how feedback and re-rolls work. Written for maintainers; contributors are pointed at CONTRIBUTING.md. Kindling/Hunt-Generation.md is a strict subset of PEAK-Template.md, which covers the same scoping step plus execution and findings. Kept at the user's direction with a header pointing to both PEAK-Template.md and Hunt-Template.md rather than deleted. Nothing in the repo linked to Kindling/ at all, which is why those templates rotted unnoticed. Adds a Templates section to the root README covering all four, plus a maintainer pointer to Review-Process.md. Also fixes the README's manual submission link, which was broken two ways: it named template=hunt_submission_form.yml, which does not exist, and it forced labels=manual-submission, routing submitters into process-manual-issue.yml — the workflow whose script was deleted in 0b408cb. Now points at hunt_template.yaml and lets that template apply its own labels, so submissions reach process-hunt-submission.yml, which works. The underlying problem is unchanged and still needs a decision: there are two manual submission templates, and manual_submission.yml still applies the manual-submission label that triggers the broken workflow. Verified: pytest 70/70, npm test 11/11, type-check clean, all links resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Completes the cleanup started in 0b408cb (2025-06-21), which deleted scripts/process_manual_submission.py and submit-manual.html but left behind the issue template and workflow that depended on that script. .github/workflows/process-manual-issue.yml invoked the deleted script, so applying the manual-submission label would have failed. In practice it never did: the label has never been applied to a single issue, open or closed, so every run of that workflow skipped at the job guard. The failure was latent, not active, which is why it went unnoticed for fourteen months. .github/ISSUE_TEMPLATE/manual_submission.yml was the only thing that applied that label, and it duplicated hunt_template.yaml — which covers the same manual submission path and routes to process_hunt_submission.py, which exists and works. Anyone who picked the duplicate from the template chooser would have gotten silence. Removing both leaves one manual submission path instead of two, and it is the working one. The README already points at it as of 34a4a4f. Verified: no remaining references to the label, template, workflow, or script anywhere in the repo; all remaining issue templates and workflows parse as valid YAML; pytest 70/70, npm test 11/11, type-check clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation across the repo had drifted from the code. This fixes what was wrong, fills in what was never written, and removes a submission path that could not work.
What was stale
Hunt counts (README). Embers and Alchemy were off by roughly 2x — the README said 17 and 14 against actual counts of 34 and 27. Library total said 130+ against 320. Now 300+ / 250+ / 30+ / 25+, rounded to match the existing
N+convention so they don't re-stale on every merge. Contributors badge 29+ → 38+.Model ID.
2a76552migrated the scripts to Sonnet 5 without updating the docs, leaving three different values in the repo. The README and testing guide still saidclaude-sonnet-4-5-20250929, andhome.htmlsaidclaude-sonnet-4-6, which is not a real model ID and was user-facing on the site. All six references now agree with the scripts.scripts/README.md. Untouched since June 2025 and describing a codebase that no longer exists — it documentedparse_hunts.py,test_runner.py,config_manager.py,logger_config.py,validators.py, and ahearth_config.json, none of which are in the repo, while 18 of the 22 actual scripts went undocumented. Rewritten around what the scripts do, grouped by role, with a "Run by" column mapping each to the workflow that invokes it, since almost nothing here is run by hand.docs/TESTING_GUIDE.md. Predatedscripts/tests/entirely and never mentioned pytest. Adds a section up front covering all seven test files and the fixtures layout. Also replaces a command that pointed at a nonexistentscripts/test_database_speed.pywith a runnable index-currency check, since a stale index is the failure mode that actually affects duplicate detection.Keepers/Review-Process.md. A five-line TODO stub that had never been written. Now documents the label-driven pipeline, which automated checks run and when, what reviewers should assess per hunt category, and how re-rolls work.Kindling/. Nothing in the repo linked to it, which is why those templates rotted unnoticed. Adds a Templates section to the README.Hunt-Generation.mdis a strict subset ofPEAK-Template.md; kept, with a header pointing at the fuller version.Two bugs found along the way
The README's manual submission link was broken two ways. It named
template=hunt_submission_form.yml, which does not exist, and forcedlabels=manual-submission, routing submitters into a workflow whose script was deleted in0b408cb. Now points athunt_template.yamland lets that template apply its own labels, so submissions reachprocess_hunt_submission.py, which works.The dead path itself is removed.
0b408cb(June 2025) deletedscripts/process_manual_submission.pybut left behind the workflow that invoked it and the issue template that triggered it. The label has never been applied to a single issue, open or closed, so every run of that workflow skipped at the job guard — the failure was latent rather than active, which is why it went unnoticed for fourteen months. Both files removed, leaving one manual submission path instead of two.Correction carried in the history
An intermediate commit claimed CI does not run the pytest suite. It does —
validate-hunt-schema.ymlrunspytest scripts/tests/ -von every PR, deliberately without a path filter so it can serve as a required status check.34a4a4fcorrects this in both affected documents.Verification
Every command written into these documents was executed before committing. Every script, workflow, and link reference was checked to resolve. All remaining issue templates and workflows parse as valid YAML.
pytest70/70 ·npm test11/11 ·npm run type-checkcleanNote for reviewers
Prettier normalized pre-existing formatting drift in the markdown files it touched (table padding,
*italic*→_italic_, blank lines before lists). In the first commit only nine lines are semantic; the rest is formatting.🤖 Generated with Claude Code