LearnNewsExamplesServices
Frontmatter
id10737
titleSkill payload audit: extend #10537 methodology to remaining workflow manuals
stateClosed
labels
documentationenhancementcontributor-experienceai
assigneesneo-opus-4-7
createdAtMay 5, 2026, 11:06 AM
updatedAtMay 9, 2026, 11:23 PM
githubUrlhttps://github.com/neomjs/neo/issues/10737
authorneo-opus-4-7
commentsCount0
parentIssue10733
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 5, 2026, 5:00 PM

Skill payload audit: extend #10537 methodology to remaining workflow manuals

Closeddocumentationenhancementcontributor-experienceai
neo-opus-4-7
neo-opus-4-7 commented on May 5, 2026, 11:06 AM

Context

Sub 4 of Epic #10733. Depends on Sub 1 baseline. Extends #10537's pr-review-only decision rule to the remaining high-load skill payloads, with two amendments per @neo-gpt's Depth Challenges:

  1. Methodology extended to correction-cycle metrics, not just loaded-byte delta
  2. Per-harness lazy-load verification — modularization is not context reduction unless the active client truly lazy-loads

The Problem

The references/ payloads in .agents/skills/ total 2,537 lines across 21 files. #10537 targets pr-review-guide.md §5.3 only. The other high-load payloads (line counts from local sweep):

Payload Lines Trigger frequency
pull-request-workflow.md 314 Every commit cycle
epic-review-workflow.md 204 Per epic intake
ticket-create-workflow.md 145 Per ticket creation
ticket-triage-workflow.md 133 Per labelable triage
session-sunset-workflow.md 116 Per session-end

Same Map vs World Atlas pressure as pr-review-guide.md, just differently-distributed across triggers.

The Architectural Reality

  • .agents/skills/*/references/*.md (the payloads above)
  • .agents/skills/*/SKILL.md routers (7-12 lines each, explicitly preserved)
  • learn/agentos/ProgressiveDisclosureSkills.md — architectural reference
  • .agents/skills/create-skill/references/skill-authoring-guide.md — authoring discipline

The Fix

Apply the #10537 decision rule (condition-gated narrow / mid-tier / common / universal) — extended with correction-cycle metrics — to each of the candidate payloads above.

Default: keep monolithic when the workflow is a single atomic cognitive pass; split only when sections are condition-gated AND skipped in a measurable share of real runs AND the per-harness loaded-byte delta is empirically positive.

Some manuals (e.g., epic-review-workflow.md, epic-resolution-workflow.md) may be legitimately monolithic per @neo-gemini-3-1-pro's Depth Challenge — they represent single atomic cognitive passes. Document the keep-monolithic rationale explicitly; don't split for the sake of splitting.

Per-harness verification gate (per @neo-gpt): any extraction PR must demonstrate empirical per-harness loaded-byte reduction (/memory show, /memory, Codex audit), not just smaller files on disk.

SKILL.md router preservation: explicit invariant — this sub does NOT expand router bodies. Routers stay at 7-12 lines. "Skill restructuring" means payload references, NOT router-body expansion.

Acceptance Criteria

  • (AC12) Each candidate payload classified per the extended decision rule (4-tier + correction-cycle adjustment)
  • (AC13) Extraction PRs filed only where the empirical per-harness loaded-byte delta supports it; explicit "keep monolithic" rationale documented for the rest
  • (AC14) Post-extraction: correction-cycle metrics measured against AC2 baseline; false-win regressions reverted
  • (AC11a) SKILL.md routers preserved at 7-12 lines (no router-body expansion)

Out of Scope

  • pr-review-guide.md §5.3 — owned by #10537
  • AGENTS.md compaction (Sub 2 owns)
  • Boot-ramp changes (Sub 3 owns)
  • Asset template changes (Sub 5 owns)
  • SKILL.md router restructuring — invariant per AC11a + Epic Out-of-Scope
  • Splitting payloads that prove single-atomic-cognitive-pass on measurement (default-monolithic per @neo-gemini-3-1-pro)

Related

  • Parent Epic: #10733
  • Sibling open ticket: #10537 — pr-review-guide.md §5.3 pilot. Sub 4 depends on its measurement methodology (extends, not replaces)
  • Origin discussion: #10732 (especially @neo-gpt's external-source addendum and modularization-not-reduction trap)

Origin Session ID: 7e52099b-9632-4c67-a2a1-4e1a1ad1c414

Retrieval Hint: query_raw_memories(query="skill payload audit pull-request-workflow epic-review-workflow ticket-create lazy-load verification 10733 10732 10537")

tobiu referenced in commit 6b3bf98 - "refactor(agentos): compress 2 of top 5 skill payloads (#10737 partial) (#10745) on May 5, 2026, 3:56 PM
tobiu referenced in commit 10242ef - "docs(agents): finalize #10737 payload audit (keep-monolithic verdicts) (#10747) on May 5, 2026, 5:00 PM
tobiu closed this issue on May 5, 2026, 5:00 PM