docs: fix stale meta-tooling docs found by self-maintenance review - #29
Merged
Merged
Conversation
- target_artifacts.md: opsward-diagnose/opsward-maintain/opsward-generate skill names (was diagnose-setup/maintain-docs, never the real names); replace the fictional --cross-agent symlink section with what --agents-md actually generates (a real file, not a symlink); point to docs_catalog.md as the doc-type SSOT. - architecture.md: add recommend.py to the module table; move AGENTS.md output and skill spec validation out of "future extension points" (both shipped); remove the "custom YAML rubric" extension point, which contradicts .claude/rules/scoring-invariants.md (hardcoded constants, no override file). - scoring_rubric.md: replace the never-implemented per-skill 6-dimension weighted table with the real model in score.py::_score_skills (40% has SKILL.md / 30% has description / 30% spec compliance, averaged). - docs_guide.md: add the missing roadmap.md, testing.md, decisions/ and research/ rows (the guide itself failed opsward's own freshness check). - roadmap.md: archived as v1 (10 of 12 "Concrete Next Actions" verified shipped in the codebase); the 2 open items (AGENTS.md/CLAUDE.md consistency check, awesome-claude-code submission) are called out. - ai_setup_meta_tooling.md: annotate §2.1 and §3-4 as the original research proposal, superseded by the shipped CLI + docs_catalog.md. Partially addresses #18 (self-maintenance cleanup). Not done in this pass, left for a follow-up: backfilling misc/docs/decisions/ with real ADRs, the opsward-add-scan-field / opsward-add-drift-check dev skills, refreshing file.py:NN citations in dev skills to symbol names, and a design doc for recommend.py -- each is a separate, sizeable writing task in its own right. Co-Authored-By: Claude Sonnet 5 <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.
Summary
Partially addresses #18 (opsward self-maintenance: stale-docs cleanup). All changes are docs-only, no behaviour change, verified against the current codebase:
target_artifacts.md: real skill names (opsward-diagnose/opsward-maintain/opsward-generate, wasdiagnose-setup/maintain-docs); replaced the fictional--cross-agentsymlink section with what--agents-mdactually generates (a real file); pointed todocs_catalog.mdas the doc-type SSOT.architecture.md: addedrecommend.pyto the module table; moved AGENTS.md output and skill-spec validation out of "future extension points" (both shipped); removed the "custom YAML rubric" extension point, which contradicts.claude/rules/scoring-invariants.md.scoring_rubric.md: replaced the never-implemented per-skill 6-dimension weighted table with the real model inscore.py::_score_skills.docs_guide.md: added the missingroadmap.md,testing.md,decisions/,research/rows.roadmap.md: archived as v1 — verified 10 of 12 "Concrete Next Actions" are shipped in the codebase; the 2 open ones are called out.ai_setup_meta_tooling.md: annotated §2.1 and §3-4 as the original research proposal, superseded by the shipped CLI +docs_catalog.md.The prerequisite named in #18 (5 unmerged branches touching these areas) is already resolved — all 5 (
feat/dogfood-skills#1,feat/dogfood-hooks-rules-deploy-fix#5,feat/validity-aware-scoring#7,feat/explainable-scores#9,feat/generator-output-quality#11) were merged earlier today.Not done in this pass (left open on #18)
misc/docs/decisions/with real ADRsopsward-add-scan-field/opsward-add-drift-checkdev skillsfile.py:NNcitations inopsward-add-scoring/opsward-add-template/opsward-devto symbol namesrecommend.pyEach is a separate, sizeable writing task; scoped out to land the mechanical/verifiable fixes now rather than block on the rest.
Test plan
git diff --statconfirms onlymisc/docs/*.mdfiles changed.--agents-mdbehaviour,_score_skillsweights, scoring-invariants rule) checked against current source inopsward/*.pyand.claude/rules/scoring-invariants.md.🤖 Generated with Claude Code
https://claude.ai/code/session_011HSBVhDjRU4apSLcRkavv9