Skip to content

refactor(skills): extract sections from orchestration/SKILL.md to free Tier-1 budget #594

@michael-wojcik

Description

@michael-wojcik

Problem

pact-plugin/skills/orchestration/SKILL.md is currently 610 lines, well past the ~292-line per-file post-compaction restoration budget per memory 444 (4-tier durability model investigation, PR #444 / commit 8621cc7). Content past line ~292 may not restore after compaction, creating eviction risk for critical operating instructions.

This is a hygiene issue independent of any specific feature work — the budget overrun is structural and worsens with every additive edit to the orchestration skill body.

Action

Identify candidate sections to extract into separate skills:

  • Agent dispatch templates → skills/pact-agent-dispatch (or expand existing dispatch-related skill)
  • Teachback review flow → expand skills/pact-teachback
  • Phase-by-phase principles → consolidate elsewhere (own skill or inlined into command files)
  • Agent tracking task lifecycle table → could move to a smaller skill or be replaced with a cross-ref

Restore skills/orchestration/SKILL.md to comfortably within the ~292-line budget so that the full operating reference reliably restores after compaction.

Discovered during

#591 plan-mode session 2026-04-29 (plan at docs/plans/inbox-monitor-wake-plan.md). Preparer's R3 risk surfaced the budget overrun while researching the wake-mechanism placement; user explicitly requested this be filed as a separate hygiene issue regardless of #591 outcome.

Acceptance criteria

  • skills/orchestration/SKILL.md ≤ 292 lines post-refactor.
  • All extracted content preserved in new/existing skill files with no semantic loss.
  • No agent-execution-time behavior changes (extracted skills load on the same trigger conditions as before, or via explicit cross-refs from the slimmed orchestration body).
  • Test invariant added asserting skills/orchestration/SKILL.md line count ≤ 292 (catches future regression).
  • Cross-refs from the slimmed orchestration body to extracted skills follow the slug-link form per memory Canonical Task() dispatch is mirrored inline at every consumer site (PR #457) precedent for cross-surface references.

Related memories

  • 444 — 4-tier durability model investigation; defines the ~292-line per-file restoration budget.
  • Canonical Task() dispatch is mirrored inline at every consumer site (PR #457) — load-bearing cross-ref discipline.
  • feedback_llm_docs_structural_delivery — structural > inline > warn-ref > plain-ref.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions