Skip to content

docs: fix dangling versioning pointer, align Feature spelling, add ISA design-doc aliases - #1672

Open
anikinsasha wants to merge 2 commits into
danielmiessler:mainfrom
anikinsasha:docs/versioning-canonical-home-and-isa-aliases
Open

docs: fix dangling versioning pointer, align Feature spelling, add ISA design-doc aliases#1672
anikinsasha wants to merge 2 commits into
danielmiessler:mainfrom
anikinsasha:docs/versioning-canonical-home-and-isa-aliases

Conversation

@anikinsasha

Copy link
Copy Markdown

Three small documentation consistency fixes. All three are text-only; no behavior, no code.

1. OPERATIONAL_RULES.md § Versioning is a dangling pointer

LifeosSystemArchitecture.md:305 and Skills/SkillSystem.md:218 both name OPERATIONAL_RULES.md § Versioning as the home of the standing three-level version rule. That section does not exist. The shipped install/USER/CONFIG/OPERATIONAL_RULES.md stub has exactly four sections — Tool & environment preferences, Repo conventions, Deployment, Vendor-specific rules — and no Version field.

The real canonical home is LifeosSystemArchitecture.md § Versioning itself. 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.md is 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:218see OPERATIONAL_RULES becomes see `LifeosSystemArchitecture.md` § Versioning.

2. MAJOR.MINOR.PATCHMajor.Feature.Patch in CreateSkill

skills/CreateSkill/SKILL.md:428 says MAJOR.MINOR.PATCH, while both system docs say Major.Feature.Patch and 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:326 and Workflows/UpdateSkill.md:136 both 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.md currently reads:

USE WHEN ISA, ISC, ideal state, ideal state criteria, project specification, hill-climb, articulating done.

"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:

  • "design doc" (10 chars) and "design architecture" (19) clear the six-character filter and index normally.
  • "PRD" stays below the filter, but it is still read by the model when it scans skill descriptions, and it costs three characters to carry.

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:

rg -q OPERATIONAL_RULES LifeOS/install/LIFEOS/DOCUMENTATION/LifeosSystemArchitecture.md LifeOS/install/LIFEOS/DOCUMENTATION/Skills/SkillSystem.md
rg -q MINOR LifeOS/install/skills/CreateSkill/SKILL.md
rg -q PRD LifeOS/install/skills/ISA/SKILL.md

First two return nothing; the third matches.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant