---
id: 11334
title: Refine SkillSource sub-rule metadata via trigger pointers
state: CLOSED
labels:
  - enhancement
  - ai
  - testing
  - 'agent-task:blocked'
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-13T21:30:30Z'
updatedAt: '2026-05-16T12:39:06Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11334'
author: neo-gpt
commentsCount: 1
parentIssue: 11317
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy:
  - '[x] 11320 Skill manifest lint: per-file payload cap + section-trigger declarations (Sub-A of #11319)'
blocking: []
closedAt: '2026-05-16T12:39:06Z'
---
# Refine SkillSource sub-rule metadata via trigger pointers

## Context

PR #11333 completes the immediate #11323 metadata/test gap by emitting `isAtlasMonolithSubRule` from `SkillSource` and asserting the current behavior in the focused source-unit test.

Claude's Cycle 1 review on PR #11333 approved the PR, but surfaced a valid semantic-precision follow-up: the current v1 implementation uses `pathParts.includes('references')` as a coarse approximation. That distinguishes top-level `SKILL.md` routers from payload files, but it does not distinguish workflow-map files under `references/` from extracted sub-rule sibling files.

This ticket captures that precision refinement as a post-#11320 child of Epic #11317, instead of churning an already-approved PR whose current metadata field has no downstream consumer yet.

## The Problem

The field name `isAtlasMonolithSubRule` implies a specific semantic category: a sub-rule extracted from an atlas/workflow monolith. The current v1 heuristic is broader:

- `pr-review/SKILL.md` -> router map -> `false` today, correct.
- `pr-review/references/pr-review-guide.md` -> workflow map under `references/` -> `true` today, too broad for the eventual semantic meaning.
- `pr-review/references/audits/loading-runtime-effect.md` -> extracted sub-rule sibling -> `true` today, correct.

The broad behavior is acceptable for #11323 because it is additive, currently unused by downstream routing logic, and still useful as a router-vs-payload discriminator. It should not become the permanent contract once trigger-pointer parsing exists.

## The Architectural Reality

Current source evidence:

- `ai/services/knowledge-base/source/SkillSource.mjs` currently derives `isAtlasMonolithSubRule` from path membership under `references/`.
- #11320 owns the trigger-aware workflow lint primitive, including AC4 section-trigger parsing for the canonical `<!-- trigger: ... -> read ... -->` pointer shape.
- Discussion #11316 / Epic #11317 owns KB semantic recall for skill chunks.
- Discussion #11314 / Epic #11319 owns trigger-aware workflow structure and Map vs World Atlas recursive-application discipline.

Therefore the precise discriminator belongs after #11320 AC4 lands: `SkillSource` should identify files that are targets of trigger-pointer declarations from workflow maps, not every file under `references/`.

## The Fix

Refine `SkillSource` metadata extraction to use trigger-pointer knowledge once the #11320 parser contract is available.

Expected shape:

1. Reuse or share the section-trigger parser from `ai/scripts/lint-skill-manifest.mjs` rather than inventing a second incompatible parser.
2. Build a per-skill set of declared trigger-pointer target paths.
3. Emit `isAtlasMonolithSubRule: true` only for chunks whose source file is a declared target path.
4. Keep a conservative fallback for skills without trigger-pointer metadata so existing KB ingestion remains backwards-compatible.
5. Update `SkillSource.spec.mjs` with fixtures covering all three categories: top-level router, workflow map under `references/`, and extracted sub-rule sibling.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `SkillSource` chunk metadata `isAtlasMonolithSubRule` | #11316 / #11317 plus #11314 / #11319 recursive-application discipline | True only when the file is a trigger-pointer target extracted from a workflow map | Conservative v1 path heuristic may remain only where no trigger-pointer index exists | Inline JSDoc / source comment documenting approximation vs precise mode | Focused Playwright unit fixture with router, workflow map, and sub-rule sibling |
| Trigger-pointer parser contract | #11320 AC4 | Reuse or share parser output rather than duplicating syntax | Halt or keep v1 behavior if #11320 parser is not landed | #11320 implementation docs/tests | Static parser tests plus SkillSource integration unit test |

## Acceptance Criteria

- [ ] AC1: Verify #11320 AC4 has landed or expose a shared parser helper as part of this work if it has not.
- [ ] AC2: `SkillSource` no longer treats every `references/**` file as an extracted sub-rule when trigger-pointer data is available.
- [ ] AC3: `SkillSource` identifies trigger-pointer target files and emits `isAtlasMonolithSubRule: true` for those chunks.
- [ ] AC4: Workflow-map files under `references/` that contain pointers but are not themselves target files emit `isAtlasMonolithSubRule: false`.
- [ ] AC5: Top-level `SKILL.md` router files continue to emit `false`.
- [ ] AC6: Backwards compatibility is preserved for skills without trigger-pointer declarations.
- [ ] AC7: Focused Playwright unit coverage extends `test/playwright/unit/ai/services/knowledge-base/source/SkillSource.spec.mjs` with router / workflow-map / sub-rule sibling fixtures.
- [ ] AC8: PR body cites #11320 dependency state and does not close Epic #11317.

## Out of Scope

- Implementing the #11320 trigger-pointer parser itself, unless it still does not exist when this ticket is picked up and the implementation explicitly chooses to share a parser helper.
- Changing the public `type: skill` MCP query schema from #11326.
- Changing the broader SkillGraph / Memory Core topology.
- Renaming `isAtlasMonolithSubRule` before downstream consumers exist; this ticket refines semantics, not the field name.

## Avoided Traps / Gold Standards Rejected

- **Fixing inside PR #11333:** rejected because PR #11333 is approved, CI green, and the issue is an Approve-grade follow-up with no downstream consumer yet.
- **Permanent path-only classification:** rejected because `references/` contains both maps and extracted sub-rules.
- **Second parser implementation:** rejected because duplicate syntax parsing would drift from #11320's lint contract.
- **Reactive KB watcher:** remains out of scope per Discussion #11316 Option D rejection.

## Related

- Parent Epic: #11317
- Current v1 metadata/test PR: #11333
- Source implementation: #11321
- Source-unit coverage: #11323
- Trigger-aware workflow primitive: #11320
- Trigger-aware workflow epic: #11319
- Discussions: #11316, #11314

Origin Session ID: d6d89930-f408-42a0-b60e-ec4487a8cc46
Retrieval Hint: "SkillSource isAtlasMonolithSubRule trigger-pointer precision PR #11333 follow-up"

## Timeline

- 2026-05-13T21:30:31Z @neo-gpt added the `enhancement` label
- 2026-05-13T21:30:31Z @neo-gpt added the `ai` label
- 2026-05-13T21:30:32Z @neo-gpt added the `testing` label
- 2026-05-13T21:30:32Z @neo-gpt added the `architecture` label
- 2026-05-13T21:30:32Z @neo-gpt added the `model-experience` label
- 2026-05-13T21:30:46Z @neo-gpt added parent issue #11317
- 2026-05-13T21:30:50Z @neo-gpt marked this issue as being blocked by #11320
- 2026-05-13T21:30:51Z @neo-gpt cross-referenced by PR #11333
- 2026-05-13T21:36:23Z @neo-gemini-pro cross-referenced by PR #11335
- 2026-05-13T21:54:36Z @neo-opus-ada cross-referenced by PR #11338
- 2026-05-15T19:09:58Z @neo-gpt cross-referenced by #11437
- 2026-05-16T03:11:21Z @neo-gpt assigned to @neo-gpt
- 2026-05-16T03:15:09Z @neo-gpt added the `agent-task:blocked` label
### @neo-gpt - 2026-05-16T03:15:22Z

**Input from GPT-5.5 (Codex):**

> ● [BLOCKED]
> 
> Implementation branch is pushed, but this Codex harness could not create the PR.
> 
> **Branch:** `codex/11334-skillsource-trigger-pointers`  
> **Commit:** `22166d0fb feat(ai): refine SkillSource trigger-pointer sub-rules (#11334)`
> 
> **Implemented:**
> - `SkillSource` reuses the existing `parseSectionTriggers` helper from `ai/scripts/lint-skill-manifest.mjs`.
> - `isAtlasMonolithSubRule` now marks only declared trigger-pointer target files when a skill has trigger metadata.
> - Legacy skills without trigger-pointer metadata keep the conservative `references/**` fallback.
> - Focused fixture coverage covers router, workflow map, declared sub-rule target, and legacy fallback.
> 
> **Validation:**
> - `npm run test-unit -- test/playwright/unit/ai/services/knowledge-base/source/SkillSource.spec.mjs` — 3 passed.
> - `git diff --check origin/dev...HEAD` — passed.
> - `node ai/scripts/lint-skill-manifest.mjs --base origin/dev` — passed.
> - Branch freshness before push: `merge-base HEAD origin/dev == origin/dev`.
> 
> **Blocker:**
> `gh pr create --base dev --head codex/11334-skillsource-trigger-pointers ...` failed with `error connecting to api.github.com`; the escalated retry was rejected by the Codex policy reviewer. Per policy, I am not attempting an indirect PR-creation workaround.

- 2026-05-16T03:20:07Z @neo-opus-ada cross-referenced by PR #11446
- 2026-05-16T12:39:07Z @tobiu referenced in commit `97616f2` - "feat(ai): refine SkillSource trigger-pointer sub-rules (#11334) (#11446)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-16T12:39:07Z @tobiu closed this issue

