docs: delete history, strip check-docs, voice lives in the skill - #230
Merged
Merged
Conversation
history/ is gone. The knowledge is in the pages, which is what archiving it was for, and 15 frozen specs nobody maintains were 1,000 em dashes and a second place to look. The reorg had also left components/osapi-justfiles/specs/ behind, which the git mv to history missed. Gone with the rest. check-docs was 128 lines and half of it guarded against Spec Kit leaking into the docs: FR- labels, MUST, user stories, acceptance scenarios, success criteria, source footers. None of that can happen now. It is 78 lines and three checks that each pay for themselves: every relative link resolves, every page is linked from its component README, and no em dashes. It covers every markdown file somebody wrote rather than only components/, which is how 32 em dashes accumulated in two skills. The voice guidance is a reference in the document skill, where the skill that writes the docs reads it. It carries the required unslop pass and the specific tells, including the ones I kept producing: significance instead of substance, commentary about the document, aphorisms that sound like wisdom and tell you nothing to do. Three passages in the component docs fixed. osapi-justfiles announced its own honesty before saying six words. osapi-orchestrator argued with the codebase's vocabulary for five sentences before defining either term. ARCHITECTURE.md had a heading about where facts are filed rather than about the system.
github-actions
Bot
added
kind/spec
kind/yaml
kind/contributing
kind/agents
kind/just
labels
|
Thank you for contributing to this project! 😊🕹️ |
history/ is gone. The knowledge is in the pages, which is what archiving it was for, and 15 frozen specs nobody maintains were a second place to look and a thousand em dashes. The reorg had also left components/osapi-justfiles/specs/ behind, which the git mv into history missed. scripts/ is gone: check-counts, check-docs and validate-skills, plus the skill-lint workflow that called a recipe that no longer exists. What replaces them is the skill and a reader. just test is markdown and justfile formatting now. Fourteen page footers cited ../../history/ paths that no longer resolve. Nothing caught them because they are backticked rather than links, which is the kind of thing a script would not have caught either. Spec Kit vocabulary is out of the prose. "The corpus" was never defined anywhere and an onboarding reading said so; it is "these docs" now. ARCHITECTURE.md claimed osapi's memory mentions neither the reconnection nor the logging behaviour, which stopped being true when transport.md was written, so it cites that page instead. Hardcoded counts are out of the README: six repositories, twelve subject pages, fifteen specifications. Each was wrong the day something changed, and the skills section right below them explains why no skill hardcodes an inventory. The voice is a reference in the document skill, where the skill that writes the docs reads it. It carries the required unslop pass. Three passages fixed: osapi-justfiles announced its own honesty before saying six words, osapi-orchestrator argued with the codebase's vocabulary for five sentences before defining either term, and ARCHITECTURE.md had a heading about where facts are filed rather than about the system.
This was referenced Oct 1, 2026
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.
Four things.
history/ is gone
15 frozen specs nobody maintains, holding about 1,000 em dashes and a second place to look for anything. The knowledge is in the pages under
components/, which is what archiving them was for.The reorg had also left
components/osapi-justfiles/specs/behind, which thegit mvintohistory/missed. Gone with the rest.check-docs is 78 lines instead of 128
Half of it guarded against Spec Kit leaking into the docs:
FR-labels,MUST, user stories, acceptance scenarios, success criteria, per-paragraph source footers. None of that can happen now.What is left is three checks that each pay for themselves:
It now covers every markdown file somebody wrote, not just
components/. That gap is how 32 em dashes accumulated inadd-a-domainandorg-status: the skills were never held to the rule the docs were held to. All 32 gone, andskill-lintcaught the one replacement that put a colon inside a YAMLdescriptionand broke the frontmatter.The voice is a reference in the document skill
.claude/skills/document/references/voice.md, where the skill that writes the docs reads it. It carries the requiredunsloppass and the specific tells, including the ones I kept producing: significance instead of substance, commentary about the document, and aphorisms that sound like wisdom while telling you nothing to do.Three passages in the component docs
osapi-justfilesannounced its own intellectual honesty and then delivered six words: "What it is worth, stated as what is true rather than as what would be reasonable: the contract is whatevermainholds." Now just the second half.osapi-orchestratorargued with the codebase's vocabulary for five sentences before defining either term. Now defines them first, then one line noting the code calls all ten "guards".ARCHITECTURE.mdhad a heading about where facts are filed rather than about the system: "What no single repository states" is now "Facts that span repositories".Supersedes #229.
🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c