[Epic] Trigger-Aware Workflows: Per-Section Triggers Apply Map vs World Atlas Recursively (Discussion #11314 graduation)

Context

Graduates Discussion #11314 (3x APPROVED consensus 2026-05-13T18:48:48Z: @neo-gemini-3-1-pro Cycle-1 + body-author signal + @neo-gpt Cycle-2 + @neo-opus-4-7 GRADUATION_PROPOSED with absorbed peer-refinement Cycles).

Friction source: post Epic #10733 cleanup, atlas-monoliths re-grew empirically (per origin/dev commit b0ab939b3 HEAD):

• pr-review-guide.md: 45,210 B (May 5) → 57,388 B today (+27% / 8 days)
• pull-request-workflow.md: 22,638 B (May 5) → 33,463 B today (+48% / 8 days)
• AGENTS.md: 11,742 B baseline → 27,017 B today (+130% / 6 weeks)

PR #11278 shipped lint-skill-manifest.mjs with uniform 80K aggregate payloadBudget — empirically misses every atlas-monolith (21/25 skills <50% utilized). Atlas files inside references/ violate Map vs World Atlas within the references/ tier when rare-trigger sections live in always-loaded-on-skill workflow body.

Operator framing converged 2026-05-13T16:14Z: "multiple angles here are possible. at the very least: inner skill documents: we MUST codify that the bare always relevant minimum is in there. and edge cases as ONE LINE triggers."

Operator priority framing 2026-05-13T19:06Z (relayed via @neo-gemini-3-1-pro): "bloated skills are the immediate danger to the swarm. We must execute on #11314 and #11316 now while the context is hot."

The Architectural Reality

.agents/skills/create-skill/references/skill-authoring-guide.md §"Map vs World Atlas Constraint Placement" (lines 106-111) documents the discipline but enforcement is review-time discipline-only. Empirically fails — atlases re-grow.

Recursive Map vs World Atlas (HNSW Middle-Layer enforcement): workflow files (references/<workflow>.md) need to apply Map vs Atlas RECURSIVELY at the section level. Always-relevant sections stay inline (workflow Map content earning its slot); edge-case sections extract to sub-rule sibling files (Atlas content) behind explicit one-line trigger pointers.

HNSW Topography frame (Discussion #11314 §1.5, cross-coupled with #11316):

• Top Layer (sparse, always-loaded): SKILL.md routers — routerByteBudget (already enforced)
• Middle Layer (modular chunks, conditional on skill-trigger): references/<workflow>.md + references/<sub-rule>.md — perFilePayloadBudget + per-section trigger extraction (THIS EPIC)
• Bottom Layer (dense, lazy semantic-search): code + memory + KB-indexed .agents/skills/** (handled separately in Gemini's #11316 Epic; cross-couples via isAtlasMonolithSubRule metadata)

The Fix

Extend .agents/skills/skills.manifest.json schema + lint-skill-manifest.mjs + .github/workflows/skill-manifest-lint.yml to enforce the recursive Map vs World Atlas pattern via per-section trigger declarations.

Canonical section-trigger syntax (Discussion #11314 OQ1 resolved):

<h2 class="neo-h2" data-record-id="5">§5.3 MCP-Tool-Description Budget Audit</h2>

<!-- trigger: pr touches ai/mcp/server/*/openapi.yaml → read ./audits/mcp-tool-description-budget.md -->

The workflow file contains bare always-relevant minimum: section header + one-line trigger pointer. Full sub-rule body lives in sibling file under references/<sub-rule>.md or references/<category>/<sub-rule>.md. Lint detects sections whose body exceeds N lines but whose declared trigger fires rarely → extraction signal.

Sub-Issue Decomposition

Per Discussion #11314 §8 graduation target (split-not-bundled per @neo-gpt body-repair #4 to bound migration blast-radius):

• Sub A (this Epic's first sub-ticket — implementation primitive, single bounded PR): extend skills.manifest.json schema with per-section trigger field shape + update lint-skill-manifest.mjs to walk + audit + flag mismatches. Schema migration: add perFilePayloadBudget field per-skill manifest entry; add section-trigger declaration parser. Does NOT include workflow migrations.
• Sub B — first proof-of-pattern migration: migrate pr-review-guide.md (largest atlas-monolith at 57,388 B / 45 sections). Extract rare-trigger sections (§5.3 MCP-Tool-Description Budget Audit, §5.4 Contract Completeness Audit, §7.8 Loading-Runtime-Effect Substitution, others identified during sub-A lint output) to references/audits/<name>.md sibling files. Single skill scope; lint validates post-migration.
• Sub C — second proof-of-pattern migration: migrate pull-request-workflow.md (33,463 B). Extract rare-trigger sections; consume the same Sub-A primitive.
• Sub D+ — remaining atlas migrations (one skill per PR, sequential): ideation-sandbox-workflow.md (23,025 B), structural-pre-flight-workflow.md (18,989 B), etc. Sequence determined post-Sub-A by empirical lint output.

Each migration sub-ticket is one PR bounded to one skill. Cross-#11316 coupling: each extracted sub-rule file's isAtlasMonolithSubRule: true metadata flag (post-#11316 KB-ingestion ship) enables targeted semantic retrieval.

Contract Ledger Matrix

Acceptance Criteria

• AC1: Schema extension shipped (Sub-A). skills.manifest.json schema includes perFilePayloadBudget field per-skill entry + section-trigger declaration support; backwards-compatible with current manifest (uniform 80K aggregate retained as outer ceiling).
• AC2: Lint walks + audits + reports (Sub-A). lint-skill-manifest.mjs parses per-section HTML-comment trigger declarations + applies section_size × inverse(trigger_frequency) heuristic to flag extraction candidates. Empirical-floor calibration per skill per Discussion #11314 OQ3 resolution.
• AC3: /create-skill discipline updated (Sub-A). skill-authoring-guide.md §"Map vs World Atlas Constraint Placement" + §"Slot-Rule Discriminator" updated to reference new per-section primitive. Operator OQ1-resolved canonical syntax <!-- trigger: [condition] → read [sub-rule.md] --> documented.
• AC4: §5.2 Step-Back sweep partial closure (Discussion #11314 §7 — migration blast-radius). Sub-tickets B+ explicitly bounded to one skill per PR; lint validates post-each-migration to prevent blur.
• AC5: NO absolute monolithic exception (Discussion #11314 OQ2 resolved). cognitive-load-baseline-2026-05.md §4 "keep-monolithic" verdicts superseded for edge-case extraction concern — session-sunset-workflow.md, epic-review-workflow.md, ticket-triage-workflow.md all subject to same rule.
• AC6: First proof-of-pattern migration shipped (Sub-B). pr-review-guide.md migrated; lint validates; rare-trigger sections moved to references/audits/<name>.md sibling files.
• AC7: Cross-#11316 coupling preserved. Each extracted sub-rule file gets isAtlasMonolithSubRule: true metadata flag (consumed post-#11316 KB-ingestion ship). Coordination: this Epic's Sub-A defines the metadata schema field; #11316's Epic consumes it.
• AC8: Substrate-budget compliance (per AGENTS.md §13 + pull-request-workflow.md §1.1). Each sub-ticket PR loaded-context-neutral or net-reducing. AC10 enforcement via compress-to-trigger strict-default disposition (already in §1.1 per PR #11303).
• AC9: Cross-family review consensus. Per #11217 consensus mandate for high-blast substrate: each sub-PR requires at least 1 non-author cross-family APPROVED + operator decisional gate. @neo-gpt designated primary epic-review gatekeeper per operator distribution 2026-05-13T19:06Z.
• AC10: Discussion archaeology preserved. Discussion #11314 stays open with [GRADUATED_TO_TICKET] resolution marker post-Epic-#N file; closes-as-completed only when ALL sub-tickets land per epic-resolution-workflow.md.

Out of Scope (explicit)

• AGENTS.md byte budget / harness truncation — different surface (always-loaded turn substrate not per-skill); separate Sandbox if surfaced
• KB ingestion of .agents/skills/** — different substrate (KB service code, ChromaDB pipeline); Gemini's #11316 Epic lane
• AI-reviewer mechanical CI gate — Discussion #11237 unbuilt graduation; separate ticket per cross-family rotation
• assets/, scripts/ auxiliary folders — per /create-skill source-of-authority correction (Payload = references/*.md only); not folded into payloadBudget
• Load-profile / cross-skill aggregate budget — Discussion #11314 Option E DEFERRED; sibling Sandbox post this Epic
• #11313 Lane 1 ticket disposition — close-as-superseded post Epic file (handled separately)
• Semantic LLM-quality scoring — bytes/counts only, per #11275 §Out of Scope carried forward

Avoided Traps / Gold Standards Rejected

• Per-section metadata bloat on every section — narrower framing adopted (always-relevant inline, edge-case → one-line trigger pointer) per operator directive 16:14Z + @neo-gpt body-repair #1
• Hard per-file byte cap alone — audits/loading-runtime-effect.md was extracted at 2026-05-12 (file-level cap satisfied) yet pr-review-guide.md regrew to 57,388 B; per-file caps without trigger awareness produce arbitrary splits
• Periodic manual compression audits — manual is O(N) on substrate evolution rate, bounded by operator-V-B-A bandwidth; the very pattern this Epic addresses
• Token-budget aggregate-only enforcement — already empirically failed via #11278 uniform 80K (21/25 skills <50% utilized; misses 57 KB monoliths)
• Bundling lint primitive + migrations in single PR — @neo-gpt body-repair #4 explicit: lint/schema primitive PR ≠ workflow-migration PR. Migration blast-radius bounded by one-skill-per-PR discipline (Discussion #11314 §5.2 partial-ack)
• Bundling KB ingestion (#11316 scope) — operator clarification 16:21Z "multiple ideation sandboxes allowed"; sibling Epic boundary clean

Related

• Discussion #11314 graduation (3x APPROVED consensus reached 2026-05-13T18:48:48Z)
• Sibling Epic for #11316 (Gemini-authored; Skills KB Ingestion; couples via isAtlasMonolithSubRule metadata)
• Predecessor #11275 / PR #11278 (aggregate payloadBudget shipped; this Epic extends to per-section)
• Sibling #11313 (paused per operator Sandbox-first directive; close-as-superseded by Sub-A post Epic file)
• Discipline anchor: .agents/skills/create-skill/references/skill-authoring-guide.md §"Map vs World Atlas Constraint Placement" + §"Slot-Rule Discriminator" + §"Byte Budget for SKILL.md Routers"
• Empirical anchor: learn/agentos/measurements/cognitive-load-baseline-2026-05.md §1.1 (harness truncation) + §2.1 (skill payload baseline) + §4 (keep-monolithic verdicts — superseded by AC5)
• HNSW reference primitive: ChromaDB indexing (Memory Core + KB)
• Pattern empirical validation: pull-request skill 4-sub-rule-sibling pattern + pr-review/audits/loading-runtime-effect.md extraction (2026-05-12)
• Operator distribution mandate: 2026-05-13T19:06Z — @neo-opus-4-7 lane #11314 / @neo-gemini-3-1-pro lane #11316 / @neo-gpt epic-review gatekeeper

Origin Session ID

c2d47e91-625f-4ebf-b066-49442f465830

Handoff Retrieval Hints

• Semantic: query_raw_memories(query="recursive Map vs World Atlas per-section trigger extraction HNSW Middle-Layer enforcement")
• Empirical: find .agents/skills -name "*.md" -exec wc -c {} \; | sort -rn | head -10 (atlas-monolith live ranking)
• Cross-Epic coupling: mcp_neo-mjs-knowledge-base.query_documents after #11316 ships → type: 'skill' chunks with isAtlasMonolithSubRule: true metadata = the migration-period flag
• Discussion archaeology: https://github.com/orgs/neomjs/discussions/11314 (preserved per ideation-sandbox §3 #10119 annotation pattern)