docs: fix dangling versioning pointer, align Feature spelling, add ISA design-doc aliases - #1672
Open
anikinsasha wants to merge 2 commits into
Conversation
LifeosSystemArchitecture.md:305 and SkillSystem.md:218 both cite "OPERATIONAL_RULES.md § Versioning" as the home of the standing three-level version rule. That section does not exist: the shipped USER/CONFIG/OPERATIONAL_RULES.md stub has only Tool & environment, Repo conventions, Deployment, and Vendor-specific sections, and no Version field. The real canonical home is LifeosSystemArchitecture.md § Versioning itself, which states at :303 that the standalone doc was "folded into this section, which is now the canonical reference". Line 305 pointed away from its own section, four lines below the heading. - :305 now states that this section is the standing rule. - SkillSystem.md:218 now cites LifeosSystemArchitecture.md § Versioning. OPERATIONAL_RULES.md is also the wrong home architecturally: it is a per-principal USER file shipped as an empty stub, so a system-wide rule placed there would not survive into any install. Separately, CreateSkill/SKILL.md:428 said MAJOR.MINOR.PATCH while both system docs say Major.Feature.Patch and explicitly note the middle number is "Feature, not minor". CreateSkill's own workflow files (Workflows/CreateSkill.md:326, Workflows/UpdateSkill.md:136) already use patch/feature/major, leaving :428 the only holdout. Normalized.
The ISA skill is effectively unroutable by its own vocabulary. Its USE WHEN reads "ISA, ISC, ideal state, ideal state criteria, project specification, hill-climb, articulating done" — but "ISA" and "ISC" are three characters, and the USE WHEN parser drops phrases shorter than six characters. The indexed trigger set therefore contains only the multiword phrases, and the skill's two primary names match nothing. "PRD" is a trigger nowhere in the tree, so "design a PRD" — a very common way to ask for exactly this artifact — matches no skill at all. Adds PRD, design doc, and design architecture. "design doc" (10 chars) and "design architecture" (19) clear the six-character filter and index normally; "PRD" stays useful to the model reading the description even though the index filters it, and costs three characters to carry. Description goes 440 -> 478 characters, within the 500-character recommendation. Additive only: no existing trigger is changed or removed, so no current routing behavior is altered.
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
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.
Three small documentation consistency fixes. All three are text-only; no behavior, no code.
1.
OPERATIONAL_RULES.md § Versioningis a dangling pointerLifeosSystemArchitecture.md:305andSkills/SkillSystem.md:218both nameOPERATIONAL_RULES.md§ Versioning as the home of the standing three-level version rule. That section does not exist. The shippedinstall/USER/CONFIG/OPERATIONAL_RULES.mdstub has exactly four sections — Tool & environment preferences, Repo conventions, Deployment, Vendor-specific rules — and noVersionfield.The real canonical home is
LifeosSystemArchitecture.md § Versioningitself. Line 303, inside that very section, already says the standalone Ledger doc was "folded into this section, which is now the canonical reference." Line 305 was pointing away from its own section, four lines below the heading it belongs to.There is also an architectural reason not to fix this by creating the missing section:
OPERATIONAL_RULES.mdis a per-principal USER file (one of the@-imported identity files), shipped as an empty stub. A system-wide rule placed there would not survive into any install.LifeosSystemArchitecture.md:305— the trailing sentence now states that this section is the standing rule, instead of forwarding elsewhere.SkillSystem.md:218—see OPERATIONAL_RULESbecomessee `LifeosSystemArchitecture.md` § Versioning.2.
MAJOR.MINOR.PATCH→Major.Feature.Patchin CreateSkillskills/CreateSkill/SKILL.md:428saysMAJOR.MINOR.PATCH, while both system docs sayMajor.Feature.Patchand explicitly call out that the middle number is "Feature, not 'minor.'"CreateSkill's own workflow files already agree with the system docs —
Workflows/CreateSkill.md:326andWorkflows/UpdateSkill.md:136both use patch/feature/major. Line 428 is the lone holdout in the tree, so this normalizes it.3. The ISA skill can't be routed to by its own name
skills/ISA/SKILL.mdcurrently reads:"ISA" and "ISC" are three characters each, and the USE WHEN parser drops phrases shorter than six characters. The indexed trigger set is therefore only the multiword phrases — the skill's two primary names match nothing. Separately, "PRD" is a trigger nowhere in the tree, so "design a PRD" (a very common way to ask for exactly this artifact) matches no skill at all.
This adds PRD, design doc, and design architecture:
Additive only — no existing trigger is changed or removed, so no current routing behavior is altered. The description goes from 440 to 478 characters, within the 500-character recommendation in
SkillSystem.md(and well under the 650 hard ceiling).Split into two commits so the objective fixes (1 and 2) can be taken independently of (3), which is more of a judgment call.
I understand the public repo is generated from a private source tree and that fixes are ported rather than merged — happy to reshape any of this if the private-side wording differs.
Verification, run against the tree after the change:
First two return nothing; the third matches.