Skip to content

docs(isa): sanction a remaining-work section — recording an item there is a complete disposition - #1617

Open
anikinsasha wants to merge 1 commit into
danielmiessler:mainfrom
anikinsasha:docs/isaformat-remaining-work-section
Open

docs(isa): sanction a remaining-work section — recording an item there is a complete disposition#1617
anikinsasha wants to merge 1 commit into
danielmiessler:mainfrom
anikinsasha:docs/isaformat-remaining-work-section

Conversation

@anikinsasha

Copy link
Copy Markdown

The gap

The ISA format specifies fourteen sections. None of them holds future work.

So when an ISA finishes a phase knowing there are items left, the format has no answer. Two things happen instead, and both are bad:

  1. The ISA invents a heading. ## Remaining Work, ## TODO, ## Open, ## Next — whatever that session picked. It reads fine to a human who happens to open that file, and it is invisible to every other reader, human or machine.
  2. The item leaves the artifact and becomes a card. This is the expensive one. It turns "I noticed something" into "I must now file, title, tag, and route a card." A system that charges that much for noticing gets fewer things noticed.

The second path is also self-reinforcing, because the absence of a sanctioned home is what makes carding feel like the only complete answer. Once "record it in the ISA" isn't a real disposition, every stray observation either becomes a card or evaporates.

The proposal

Add section 15, ## Remaining Work, after ## Verification. Written at VERIFY, finalized at LEARN. Omitted — like every other section — when empty.

Two semantics carry it:

1. Recording an item there is a complete disposition. It does not also require a card, an issue, or a tracker row. This is the whole point. A format that accepts the line and still demands a card has not removed any work; it has added a section.

2. An ISA's backlog is the union of its unchecked ISCs and its unchecked Remaining Work items. Both halves count, so "what does this ISA still owe" is computable from the artifact alone — no external system required to answer a question about the artifact. Unchecked ISCs stay in ## Criteria: the ID-Stability Rule forbids moving or renumbering them, and a criterion that migrates into a prose list stops being a criterion. ## Remaining Work is for work that was never an ISC of this run.

Why this belongs in the format and not in each instance

Because the claim it makes is about the artifact, not about any one project. "This ISA owes three things" should be answerable by reading the ISA, at any tier, in any domain, by any reader. That is exactly the kind of claim the fourteen-section order already exists to standardize — ## Decisions standardizes why we chose this, ## Changelog standardizes what we learned, ## Verification standardizes what passed. There is no section for what we still owe, and it is the same class of fact.

It is also already happening. The section name in this PR is not invented — it is the heading that instances converge on unprompted, which is the usual sign that the format is missing a slot rather than that authors are being undisciplined.

The companion doctrine: the hand-off test

A sanctioned section without a boundary rule would let ISAs quietly absorb work that belongs to other trees. So the spec carries the rule that decides the exceptions.

An item earns its own card only when it fails the hand-off test — when it is genuinely someone or something else's to pick up:

  • it belongs to another tree (a different repo, project, or subsystem);
  • it is blocked on someone else — an external dependency, another person, another run;
  • it will be picked up on its own schedule, not as part of this work.

Otherwise it is an ISA line. When unsure, it is an ISA line.

That asymmetry is deliberate and worth stating plainly: a line that should have been a card is still found by anyone reading the ISA. A card that should have been a line is a permanent tax on a thought. The failure modes are not symmetric, so the default should not be either.

When an item does earn a card, the line stays and names it, so the ISA remains a complete account of what it owes:

- [ ] Migrate the legacy importer — owned by the data-platform repo, tracked as #4127.

The section and the test are two halves of one thing. The section alone produces ISAs that hoard other trees' work; the test alone produces a card for every stray thought.

Two smaller things the section makes expressible

Deferred is not dropped. A dropped criterion already has a home: the tombstone form under the ID-Stability Rule (- [ ] ISC-N: [DROPPED — see Decisions]), with the reason in ## Decisions. A deferred item had no home at all. Now it does, and the distinction — whether anyone still intends to do it — is legible in the artifact instead of being lost.

A closing gate. An ISA reaching phase: complete with unchecked ISCs must either tombstone them or account for them here. Silent abandonment — a complete ISA with unexplained empty checkboxes — stops being expressible. This adds no machinery; it composes the new section with the ID-Stability Rule that already exists.

Scope of the change

One file: LifeOS/install/LIFEOS/DOCUMENTATION/Isa/IsaFormat.md. +76 / −6.

  • Section table gains row 15.
  • Tier Completeness Gate: All fourteen*All fifteen*, and the conditional-required footnote extends to cover the new section on the same pattern as ## Dependencies / ## Bridge Criteria — mandatory when the ISA closes owing work, omitted when it owes none.
  • Full section spec added after the ## Verification spec, matching the file's existing per-section idiom.
  • Version banner + H1 bumped to v2.14.0, following the file's own convention.

Notes for the reviewer

  • No Algorithm change. This is a format addition; the (Algorithm v6.25.0) pairing in the H1 is left exactly as it was. I did not renumber it — the pairing is already behind the shipped Algorithm, and that is a maintainer call, not a contributor one.
  • version: 1.5.19 frontmatter left untouched. Git history shows that field only ever moves in release commits, so it looks release-tooling-managed. Say the word if contributors are expected to bump it.
  • Drive-by, in a sentence I was already editing: the Body Sections lead-in still read "Twelve sections in fixed order" after v2.13.0 took the body to fourteen. It now reads fifteen. Happy to split this into its own commit if you would rather keep the diff single-purpose.
  • If you adopt this, four other files assert "fourteen" and would want a follow-up (deliberately not touched here, to keep the review surface to the spec itself): skills/ISA/SKILL.md (9 occurrences, including its own section table and the skill description), skills/ISA/Workflows/CheckCompleteness.md (2), skills/ISA/Workflows/Scaffold.md (2), and settings.enhancements.json (2, in the spinner-tip copy). I can extend this PR to cover them or send a second one — your preference. (Containment.md and ALGORITHM/changelog.md also match "fourteen" but are unrelated / historical.)

…e is a complete disposition

The ISA format specifies fourteen sections and none of them holds future
work. So an ISA that finishes a phase with known remaining items has nowhere
sanctioned to put them: it invents a per-instance heading no reader can rely
on, or the item leaves the artifact and becomes a card. The second path is the
expensive one — it turns "I noticed something" into "I must file, title, tag
and route a card," and a system that charges that much for noticing gets fewer
things noticed.

Adds section 15, '## Remaining Work' (after Verification), with two semantics:

1. Recording an item there is a COMPLETE disposition. No card, issue, or
   tracker row is also required. A format that accepts the line and still
   demands a card has not removed any work — it has added a section.
2. An ISA's backlog is the UNION of its unchecked ISCs and its unchecked
   Remaining Work items, so 'what does this still owe' is computable from the
   artifact alone. Unchecked ISCs stay in Criteria — the ID-Stability Rule
   forbids moving them, and a criterion that migrates into a prose list stops
   being a criterion.

Companion doctrine, the hand-off test, decides the exceptions: another tree,
blocked on someone else, or picked up on its own schedule earns a card;
everything else — and anything you are unsure about — is an ISA line. The
asymmetry is deliberate. A line that should have been a card is still found by
anyone reading the ISA; a card that should have been a line is a permanent tax
on a thought.

Also states the distinction the section makes possible: deferred is not
dropped. A dropped criterion is a tombstone under the ID-Stability Rule; a
deferred item is a live Remaining Work line. And a closing gate: an ISA
reaching phase: complete with unchecked ISCs must tombstone them or account for
them here, so silent abandonment stops being expressible.

Conditional-required at E4/E5 on the same pattern as Dependencies and Bridge
Criteria — mandatory when the ISA closes owing work, omitted when it owes none.

Drive-by in the same sentence: the Body Sections lead-in still said 'Twelve
sections in fixed order' after v2.13.0 took the body to fourteen.

No Algorithm change.
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