LearnNewsExamplesServices
Frontmatter
id11090
titleCompress new skill rules into Atlas payloads
stateClosed
labels
documentationenhancementaiarchitecturemodel-experience
assigneesneo-gpt
createdAtMay 10, 2026, 3:34 AM
updatedAtMay 10, 2026, 12:32 PM
githubUrlhttps://github.com/neomjs/neo/issues/11090
authorneo-gpt
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 10, 2026, 12:32 PM

Compress new skill rules into Atlas payloads

Closeddocumentationenhancementaiarchitecturemodel-experience
neo-gpt
neo-gpt commented on May 10, 2026, 3:34 AM

Context

PR #11085 merged a useful pr-review Cycle-1 premise pre-flight, but it also added a dense rule body directly to pr-review-guide.md: +26 lines, with the guide now at 52,296 bytes on origin/dev. The rule is valuable; the placement and density are the risk.

This is the same Map vs World Atlas pressure already captured by create-skill: keep the workflow map short and move edge cases, empirical anchors, and rare-detail payloads into conditionally loaded Atlas files. The risk is not theoretical. Discussion #10732 and Epic #10733 explicitly describe agents skimming long manuals and then paying correction-cycle costs.

This ticket is a narrow follow-up for the newly added skill-rule content, not a reopening of the broad cognitive-load epic.

The Problem

We are adding new workflow rules to fix real process failures, but the new rules can reintroduce the bloat that Progressive Disclosure was designed to remove. If every correction adds a long section to a frequently loaded skill payload, agents will skim the guide, miss the rule, and trigger another correction loop.

The immediate surfaces are:

  • PR #11085: pr-review-guide.md §9.0 Cycle-1 Premise Pre-Flight.
  • Ticket #11086 / its future PR: Double Diamond graduation guard across ideation-sandbox, epic-review, and ticket-create.

The Architectural Reality

  • .agents/skills/create-skill/references/skill-authoring-guide.md defines the Map vs World Atlas placement rule.
  • .agents/skills/pr-review/references/pr-review-guide.md is loaded for every PR review; it is the map, not the archive.
  • .agents/skills/pr-review/audits/ already exists as a granular Atlas precedent (ci-security-audit.md).
  • #10837 is an open prevention ticket for future mutation gates. This ticket is the concrete compression pass for the already-added / immediately incoming content.
  • #10733 is the broad cognitive-load epic. This ticket should remain small enough to be one PR.

The Fix

After #11086 lands, run one focused compression pass over the new process-rule additions from #11085 and #11086:

  1. Classify each newly added section with the create-skill 3-axis discriminator and disposition taxonomy.
  2. Keep only the trigger, decision rule, and pointer in high-level workflow maps.
  3. Move long rationale, empirical anchors, bias explanations, examples, and edge-case mechanics into granular Atlas payloads.
  4. Preserve behavior and reviewability: the rule must still fire when needed, just without forcing every agent to read the full case study every time.
  5. Measure wc -c before/after for each touched loaded surface and state the net delta in the PR body.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
pr-review-guide.md §9.0 PR #11085 / #11084 Keep concise Cycle-1 trigger map; move case-study depth to Atlas If extraction would obscure the rule, compress in place instead create-skill Map vs World Atlas wc -c delta + retained trigger text
#11086 skill additions Discussion #11079 / issue #11086 Keep per-skill map entries short; move Double Diamond details to Atlas where length warrants If #11086 PR already lands compactly, document no-op with evidence ideation-sandbox, epic-review, ticket-create payloads before/after byte counts
Future mutation discipline #10837 Do not duplicate #10837; cite it as the prevention gate Comment on #10837 if this pass discovers a missing guard #10837 linked PR evidence

Acceptance Criteria

  • #11085 §9.0 content is audited after merge and classified as keep, compress-to-trigger, move, rewrite, or retire.
  • If #11086 has merged, its new skill-rule content is included in the same audit; if not, the PR clearly scopes only #11085 and leaves a note.
  • Long empirical anchors / examples / bias-amplifier prose are moved to an Atlas payload when doing so reduces loaded bytes without hiding the trigger.
  • The map entry that remains in each workflow is short enough to read in one pass and includes a direct relative link to the Atlas payload.
  • No top-level SKILL.md router gains heavy content.
  • PR body reports before/after wc -c for every touched map file and Atlas file.
  • Behavior is preserved: reviewers can still apply §9.0 and the Double Diamond guard without needing prior session context.

Out of Scope

  • Reworking all pr-review-guide.md audits. #10733 / #10537 own broad modularization.
  • Changing the semantics of §9.0 or the Double Diamond guard.
  • Adding new mandatory gates beyond existing #11085 / #11086 behavior.
  • Implementing #10837 prevention gates.

Avoided Traps / Gold Standards Rejected

  • Delete the rule because it is long: rejected. The rule came from real review failure; compression must preserve it.
  • Leave all detail in the map: rejected. That recreates the skim-risk the skill system is meant to avoid.
  • Split files without measuring: rejected. Modularization is only a win if loaded-byte delta and correction-cycle behavior improve.
  • Block #11086 implementation: rejected. This is a follow-up compression pass, not a reason to stall the active guard implementation.

Related

  • PR #11085 / issue #11084 — Cycle-1 premise pre-flight landed.
  • Issue #11086 — Double Diamond graduation guard implementation.
  • Issue #10837 — prevention gate for future Progressive Disclosure violations.
  • Epic #10733 — broad cognitive-load audit.
  • Discussion #10429 — original Map vs World Atlas framing.

Origin Session ID: 20a824b0-29d1-4082-ae12-87705ec69c3f

Retrieval Hint: "Map vs World Atlas compress #11085 #11086 skill rule bloat Progressive Disclosure"

tobiu referenced in commit 8c3de6b - "docs(skills): compress pr-review premise pre-flight (#11090) (#11097) on May 10, 2026, 12:32 PM
tobiu closed this issue on May 10, 2026, 12:32 PM