Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(bin): prototype's two flow files sit at the skill root instead of references/ #114

New Issue
Closed
opened 2026-08-30 14:46:45 +00:00 by Claude · 2 comments
Claude commented 2026-08-30 14:46:45 +00:00
Collaborator
Copy Link

plugins/bin/.apm/skills/prototype/ carries its two mutually exclusive flows as LOGIC.md and UI.md at the skill root, not under references/. The skill has no references/ directory at all.

This is a genuine dispatch body — the SKILL.md "Pick a branch" section routes to exactly one of the two, and the body itself notes "the two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype." It just wires them the wrong way.

Two rules it sits outside:

  • skill-audit/references/file-structure.md:20 — "No non-spec files at the skill root: no META.md, no stray config outside the four directories." LOGIC.md and UI.md are exactly that.
  • The dispatch-body contract (ADR-0020, body-discipline.md) — each flow lives in "its own self-contained references/ file." The body wires these with plain markdown links ([LOGIC.md](LOGIC.md)) rather than a reference-file trigger.

Why it wasn't fixed in #99 wave 3

prototype's retrofit was scoped to its description ERROR (426 → 239 chars). The body is 467 words and fails nothing. Moving the two files is a structural change with mirror and deployed-path consequences, so it was held out of a wave whose discipline was "fix the ERRORs, touch nothing else." Recording it rather than letting a later agent improvise.

Scope of the fix

  1. git mv both files into references/.
  2. Rewrite the body's "Pick a branch" section to use the dispatch-table form, so the two rows carry condition → references/logic.md / references/ui.md. Consider lowercasing to match every other reference file in the corpus.
  3. Re-run scripts/sync-plugin-content.sh --all — plugins/bin/skills/prototype/ mirrors the old paths.
  4. Confirm nothing else references the old paths.

Worth checking whether any other skill has root-level flow files while in here; prototype was the only one noticed during wave 3, but the wave only looked at eight skills.

Related

Found during #99 wave 3. See also #109 (dispatch table vs. literal conditional wiring), now resolved in favour of the table.

`plugins/bin/.apm/skills/prototype/` carries its two mutually exclusive flows as `LOGIC.md` and `UI.md` **at the skill root**, not under `references/`. The skill has no `references/` directory at all. This is a genuine dispatch body — the SKILL.md "Pick a branch" section routes to exactly one of the two, and the body itself notes "the two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype." It just wires them the wrong way. Two rules it sits outside: - **`skill-audit/references/file-structure.md:20`** — "No non-spec files at the skill root: no `META.md`, no stray config outside the four directories." `LOGIC.md` and `UI.md` are exactly that. - **The dispatch-body contract** (ADR-0020, `body-discipline.md`) — each flow lives in "its own self-contained `references/` file." The body wires these with plain markdown links (`[LOGIC.md](LOGIC.md)`) rather than a reference-file trigger. ## Why it wasn't fixed in #99 wave 3 `prototype`'s retrofit was scoped to its description ERROR (426 → 239 chars). The body is 467 words and fails nothing. Moving the two files is a structural change with mirror and deployed-path consequences, so it was held out of a wave whose discipline was "fix the ERRORs, touch nothing else." Recording it rather than letting a later agent improvise. ## Scope of the fix 1. `git mv` both files into `references/`. 2. Rewrite the body's "Pick a branch" section to use the dispatch-table form, so the two rows carry condition → `references/logic.md` / `references/ui.md`. Consider lowercasing to match every other reference file in the corpus. 3. Re-run `scripts/sync-plugin-content.sh --all` — `plugins/bin/skills/prototype/` mirrors the old paths. 4. Confirm nothing else references the old paths. Worth checking whether any other skill has root-level flow files while in here; `prototype` was the only one noticed during wave 3, but the wave only looked at eight skills. ## Related Found during #99 wave 3. See also #109 (dispatch table vs. literal conditional wiring), now resolved in favour of the table.
Claude added the Kind/Enhancement
Priority
Medium
3
Reviewed
Confirmed
1
 labels 2026-08-30 15:58:52 +00:00
Claude added this to the Skills & Agents milestone 2026-08-30 15:58:57 +00:00
Claude commented 2026-08-31 08:10:11 +00:00
Author
Collaborator
Copy Link

Fixed on refactor/adr0020-skill-retrofit (not yet pushed — the PR body will carry the close)

All four steps of the stated scope are done.

  1. LOGIC.md → references/logic.md, UI.md → references/ui.md, lowercased to match every other reference file in the corpus. The skill root now holds only SKILL.md, README.md and references/.
  2. "Pick a branch" is a dispatch table, per #109's resolution — three columns (question being answered / what gets built / reference file), followed by "Resolve the row from the user's prompt, the surrounding code, or by asking if the user is around, then read only that reference — each is self-contained." The "getting this wrong wastes the whole prototype" warning and the ambiguity fallback survive underneath it.
  3. Mirror regenerated: plugins/bin/skills/prototype/ now shows references/logic.md and references/ui.md.
  4. No stale path anywhere — grep -rn 'LOGIC.md\|UI.md' across plugins/ returns nothing. The reciprocal wrong-branch cross-links inside the two files were repointed too.

Consequence worth noting: both files are now inside the deterministic dangling-references/ ERROR's scope, which they were not before. Root-level flow files were unreachable by that check entirely, so a typo in [LOGIC.md](LOGIC.md) would have shipped green.

Answer to "is any other skill like this": yes, four

All in bin, all with non-README.md markdown at the skill root:

Skill Root files
grill-with-docs ADR-FORMAT.md, CONTEXT-FORMAT.md
improve-codebase-architecture DEEPENING.md, INTERFACE-DESIGN.md, LANGUAGE.md
tdd deep-modules.md, interface-design.md, mocking.md, refactoring.md, tests.md
triage AGENT-BRIEF.md, OUT-OF-SCOPE.md

Swept across all 39 skills in all six plugins; prototype and those four were the only hits. Being filed separately rather than folded in here.

## Fixed on `refactor/adr0020-skill-retrofit` (not yet pushed — the PR body will carry the close) All four steps of the stated scope are done. 1. `LOGIC.md` → `references/logic.md`, `UI.md` → `references/ui.md`, lowercased to match every other reference file in the corpus. The skill root now holds only `SKILL.md`, `README.md` and `references/`. 2. "Pick a branch" is a dispatch table, per #109's resolution — three columns (question being answered / what gets built / reference file), followed by "Resolve the row from the user's prompt, the surrounding code, or by asking if the user is around, then read only that reference — each is self-contained." The "getting this wrong wastes the whole prototype" warning and the ambiguity fallback survive underneath it. 3. Mirror regenerated: `plugins/bin/skills/prototype/` now shows `references/logic.md` and `references/ui.md`. 4. No stale path anywhere — `grep -rn 'LOGIC.md\|UI.md'` across `plugins/` returns nothing. The reciprocal wrong-branch cross-links inside the two files were repointed too. **Consequence worth noting:** both files are now inside the deterministic dangling-`references/` ERROR's scope, which they were not before. Root-level flow files were unreachable by that check entirely, so a typo in `[LOGIC.md](LOGIC.md)` would have shipped green. ## Answer to "is any other skill like this": yes, four All in `bin`, all with non-`README.md` markdown at the skill root: | Skill | Root files | |---|---| | `grill-with-docs` | `ADR-FORMAT.md`, `CONTEXT-FORMAT.md` | | `improve-codebase-architecture` | `DEEPENING.md`, `INTERFACE-DESIGN.md`, `LANGUAGE.md` | | `tdd` | `deep-modules.md`, `interface-design.md`, `mocking.md`, `refactoring.md`, `tests.md` | | `triage` | `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md` | Swept across all 39 skills in all six plugins; `prototype` and those four were the only hits. Being filed separately rather than folded in here.
Claude commented 2026-09-01 13:59:50 +00:00
Author
Collaborator
Copy Link

Fixed by #129, squash-merged to main as 598a7c3.

LOGIC.md and UI.md moved to references/logic.md and references/ui.md (git tracked both as renames, R099). The skill root is now SKILL.md, README.md, references/ — spec-conforming.

Worth recording, because it is this issue's own trap: the move carried logic.md into the corpus nothing lints, and a later review round found it had lost three anti-patterns outright, including "Don't generalise", surviving nowhere — in a file already well under the suggestion tier, so no gate had asked for the cut. The byte-identical defect in the sibling ui.md had been restored one commit earlier and this one was missed. Both are restored at 598a7c3.

That is ADR-0020's stated anti-goal — a gate satisfied by deleting content rather than relocating it — and the general case is #117: references/ is where the contract pushes prose and where neither the size gate nor Vale looks.

Stayed open after the merge because Gitea's closing-keyword parser consumed only the first reference in Closes #99, #107, …. Closing manually.

Fixed by #129, squash-merged to `main` as `598a7c3`. `LOGIC.md` and `UI.md` moved to `references/logic.md` and `references/ui.md` (git tracked both as renames, R099). The skill root is now `SKILL.md`, `README.md`, `references/` — spec-conforming. Worth recording, because it is this issue's own trap: the move carried `logic.md` into the corpus nothing lints, and a later review round found it had **lost three anti-patterns outright**, including "Don't generalise", surviving nowhere — in a file already well under the suggestion tier, so no gate had asked for the cut. The byte-identical defect in the sibling `ui.md` had been restored one commit earlier and this one was missed. Both are restored at `598a7c3`. That is ADR-0020's stated anti-goal — a gate satisfied by deleting content rather than relocating it — and the general case is #117: `references/` is where the contract pushes prose and where neither the size gate nor Vale looks. Stayed open after the merge because Gitea's closing-keyword parser consumed only the first reference in `Closes #99, #107, …`. Closing manually.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Enhancement
Priority
Medium
3
Reviewed
Confirmed
1
Milestone
No items
No Milestone Skills & Agents
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#114
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?