pm-dispatch SKILL structural optimization: role-split loading, issue-ID removal (lessons distilled in place), probe-first startup (maintainer-directed)

[os-zhuang]

Filed by the skills seat (session session_012Gg6rMAti8ZaueWb6BRsDn) on the maintainer's instruction, skills-seat PM session chat, 2026-08-12. Direct routing under the 2026-08-10 standing authorization (maintainer-directed cards are routed by the handling PM session; provenance below).

Provenance (maintainer, verbatim, untranslated)

我开了4个项目经理,还没开始干活,5小时额度就用掉了 33% 。你评估一下项目经理的skills 是不是应该优化。

我之前看到有很多历史的 issue id,是不是没有意义并且反而浪费时间。

立一张结构卡,我觉的 处理 issue 时犯的错应该总结成经验,保留 issue id没有意义,如果ai去查原始issue,得不偿失。

还有我觉得现有的项目经理 skills 应该大幅简化,只需要说原则,不需要写细节。

The third quote rules the ID question: incident learnings are distilled into the rules themselves as self-contained lessons; issue IDs carry no value in the skill text; an AI dereferencing original issues costs more than it returns. The fourth quote (2026-08-12, later the same session) supersedes the earlier ~50–70% role-split compression target: the rewrite target is a principles-only text — state the principles, drop the procedural detail.

Measured baseline (origin/main, 2026-08-12)

• SKILL.md: 2568 lines, 118,324 chars (~33.7k CJK + ~84.6k ASCII) ≈ ~59k tokens, loaded in full by every PM session at start.
• Issue-ID citations in SKILL.md: 370 mentions, 223 unique, on 263 of 2568 lines.
• references/incidents.md: 1517 lines of ID-keyed narratives (on-demand load).
• Startup protocol reads per seat: ~50–100k tokens measured; four concurrent seats share no cache ⇒ ~150k input per seat before its first dispatch — consistent with the observed "33% of the 5-hour window before any work".

Scope — three deltas, one PR chain (design round held jointly with #7899's)

1. Principles-only drastic simplification (per the fourth ruling). Rewrite SKILL.md as principles + the state machine + role duties; delete procedural narration. Working division for the design round: a detail survives in prose only if it is (a) a genuine principle/invariant, (b) operational lookup data (e.g., the domain→package table), or (c) irreplaceable by mechanical enforcement — everything the hooks/gates/scripts already enforce (worktree guard, stash guard, ratchet, half-state checker) loses its prose twin. The earlier role-split-into-modules idea is downgraded to a design choice: at principles-only size a single small file with role sections may suffice, which is simpler than multi-file loading.

2. Issue-ID removal, lessons distilled in place (the third ruling). Every incident-backed rule rewritten to carry its lesson self-contained (failure mode + discipline + boundary), no issue-ID citations in operative text, no expectation that any reader dereferences an original issue. Design round settles: disposition of references/incidents.md (deprecated by the ruling; git history remains the archive), handling of maintainer-ruling provenance (dates + verbatim quotes carry authority; numbers go), and a mechanical guard so IDs do not creep back (lint for #[0-9]+ in skill operative text).

3. Probe-first startup. A seat's first action becomes one cheap lane-inventory query; empty queue + nothing in flight + nothing awaiting review ⇒ self-retire without further reads. Bounds idle-seat cost; delta 1 bounds the loaded-text cost.

Constraints

• Blocked-by: pm-dispatch SKILL: cloud-card comms is event-driven by ruling — roster limitation on record, notes-21 verify-before-toggle amendment, PR subscription as a hard step #7755
• Blocked-by: pm-dispatch SKILL: 5-hour usage-limit outages — queryable signals, cross-wall recovery timer (hourly cron, not send_later chains), wall-death playbook anchor #7765
• Blocked-by: pm-dispatch SKILL Guardrails: dangling sentence fragment "someone else, never dispatch a needs-user-decision issue." — the bullet it belonged to is lost #7767
• Same-file serial: position 4 in the SKILL.md hot-file queue (after PR docs(pm-dispatch): cloud-card comms is event-driven by ruling — notes-21 verify-before-toggle, PR subscription as hard step #7794 lands, then pm-dispatch SKILL: 5-hour usage-limit outages — queryable signals, cross-wall recovery timer (hourly cron, not send_later chains), wall-death playbook anchor #7765, then pm-dispatch SKILL Guardrails: dangling sentence fragment "someone else, never dispatch a needs-user-decision issue." — the bullet it belonged to is lost #7767). Targets WILL have moved by dispatch time — the dev relocates semantically on the then-current text; the two queued cards' landed deltas must survive the rewrite as principles (their procedural detail is subject to delta 1 like everything else).
• Skills updates are ADR-class: draft PR(s), ⛔ no auto-merge, no queue entry; the maintainer merges by hand.
• Model tiering mandatory clause: dispatch with model: claude-fable-5.
• Design round: held jointly with pm-dispatch step 8: triage-seat four-lens auto-adjudication of high-confidence decision cards — human floor for feature-add / ADR / protocol-change (maintainer-directed) #7899 (ruled 2026-08-12: 「六条补充都同意,设计轮和 pm-dispatch SKILL structural optimization: role-split loading, issue-ID removal (lessons distilled in place), probe-first startup (maintainer-directed) #7885 一起开」); pm-dispatch step 8: triage-seat four-lens auto-adjudication of high-confidence decision cards — human floor for feature-add / ADR / protocol-change (maintainer-directed) #7899's step-8 adjudication text is authored against the post-rewrite structure.

Process

Design round first, in the skills seat's 专题 channel (chat), outcomes recorded here. Implementation dispatches only after the design round closes and the blockers above land.

[os-zhuang]

Design round CLOSED (joint with #7899) — decisions recorded

• Whose decision: the maintainer, skills-seat PM session chat (session_012Gg6rMAti8ZaueWb6BRsDn), 2026-08-12.
• Verbatim: 「同意,还有 分诊 PM 我经常需要重新开,他的skills 如果写在文件中,那我创建 routines 时候是不是可以简化。」 (approving the four-point design proposal as recommended; the second half is a design input, resolved below)

Decisions:

• A. Target size: ~500 lines — principles + state machine (label vocabulary) + per-role duty sections + escalation bar / human floor (pm-dispatch step 8: triage-seat four-lens auto-adjudication of high-confidence decision cards — human floor for feature-add / ADR / protocol-change (maintainer-directed) #7899 text lives in the triage section) + report contract. Single file; the earlier multi-file role-split is dropped as unnecessary at this size.
• B. references/incidents.md: deleted — git history is the archive; the ID-dereference path is deprecated by ruling.
• C. High-risk sequences: mechanized into small scripts (e.g., the os-regen four-step) — prose keeps one principle line pointing at the script.
• D. Other agent texts: os-dev.md follows in its own card — filed as os-dev agent definition: principles-only simplification, following the #7885 pattern (maintainer-approved follow-up) #7903 (Blocked-by this card, shares the writing standard).

Additional design outcome (from the Routine question): the rewrite adds explicit role entry arguments — /pm-dispatch triage / /pm-dispatch steward / /pm-dispatch <domain> / /pm-dispatch epic:#<n> — so a Routine's prompt collapses to a one-liner invoking the skill; all seat behavior versions in git and updates ship as skill PRs, never as Routine re-creation. Routine-creation constraints survive as principles: create from the claude.ai UI with the GitHub connector attached (in-session create_trigger yields tool-less fired sessions), pin the model in the UI, smoke-fire once and judge by GitHub-visible output. Combined with probe-first startup (delta 3), an idle fired seat costs one query and exits.

Implementation remains blocked on the PR chain (#7794 → #7765 → #7767); dispatch follows the recorded constraints (claude-fable-5, draft PR, human merge).

---

Generated by Claude Code

[os-zhuang]

Batch conversion — this card becomes the carrier of a consolidated dispatch (sweep pattern).

Sequencing is the PM's call (named non-escalation class); the maintainer prompted the consolidation in the seat chat (2026-08-12, verbatim: 「还有哪几个 skills 任务,是不是可以合并派发」).

Composition — one cloud dev session (model: claude-fable-5), two PRs:

• PR₁ — the principles-only SKILL.md rewrite, carrying Fixes #7885, Fixes #7765, Fixes #7767, Fixes #7899:
  • pm-dispatch SKILL: 5-hour usage-limit outages — queryable signals, cross-wall recovery timer (hourly cron, not send_later chains), wall-death playbook anchor #7765's outage-detection readings and cross-wall timer discipline are authored directly as principles in the new text (landing them in the old format first, only to rewrite them, would pay for the same file twice);
  • pm-dispatch SKILL Guardrails: dangling sentence fragment "someone else, never dispatch a needs-user-decision issue." — the bullet it belonged to is lost #7767's dangling Guardrails fragment disappears with the Guardrails rewrite — the PR body must state where the restored bullet's meaning lives in the new text;
  • pm-dispatch step 8: triage-seat four-lens auto-adjudication of high-confidence decision cards — human floor for feature-add / ADR / protocol-change (maintainer-directed) #7899's adjudication protocol (fully ruled, design closed) lands in the triage duty section.
  • PR body carries the sweep-discipline itemized checklist: one line per member card — where its substance lives in the new text — so review stays per-card.
• PR₂ — os-dev.md principles-only simplification (Fixes #7903): same session, same writing standard, separate PR for a clean review surface. No cross-PR dependency.

Blocked-by collapses to #7755 alone (PR #7794 in the merge queue at this writing — its landed deltas are input to the distillation). #7765 / #7767 / #7899 are hereby batch members, not independent dispatch candidates; #7903 rides the same dispatch. Both PRs are ADR-class: draft, human merge.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 3 (skills seat) — consolidated batch carrier
Session: session_012Gg6rMAti8ZaueWb6BRsDn
Branch: claude/issue-7885-pm-skill-principles-rewrite (PR₁) + claude/issue-7903-os-dev-principles (PR₂, same dev session, branches independently off origin/main)
Worktree: cloud session — its own container and clone
Domain: domain:skills
File surface: .claude/skills/pm-dispatch/SKILL.md (whole-file rewrite) + .claude/skills/pm-dispatch/references/** (incidents.md deleted per design B; compile-surfaces disposition per design) + scripts/pm/** (ratchet lowering + ID-lint + design-C scripts, and their workflow wiring) + .claude/agents/os-dev.md (PR₂). Stop on breach; explain in the report.
Container & model: L instruction-architecture batch, mode:cloud, model: claude-fable-5 (mandatory clause — no downward discretion)
Serial constraints cleared: predecessor PR #7794 MERGED 2026-08-12 03:54Z (merge commit 2570c755 verified on origin/main; SKILL.md = 2568 lines, os-dev.md = 686 lines at that ref); zero open PRs touch pm-dispatch/** or os-dev.md (the one open skills-root PR, #7837, touches dogfood-verification/SKILL.md only — no file overlap). Batch members #7765 / #7767 / #7899 / #7903 absorbed per the composition comment above; #7885's Blocked-by: #7755 cleared by the merge.

---

Generated by Claude Code

[os-zhuang]

Dispatched (PM loop round 3, skills seat): cloud dev session session_01W3v2G9dvcfxkC4NsZ4JCE9, model: claude-fable-5, created 2026-08-12 03:57Z, outcome branch claude/issue-7885-pm-skill-principles-rewrite (+ independent claude/issue-7903-os-dev-principles for PR₂). Dispatch prompt carries: the five 2026-08-12 rulings verbatim, the closed design decisions A–D + role entry args + probe-first, the writing standard with the no-silent-semantic-loss red line (hard cap 700 — stop and report rather than raise), gate work (ratchet lowering, ID-lint, frame-sync adaptation), the two named 机制假设 to falsify, and the ADR-class terminal (two draft PRs, human merge). Collection: os-dev-report comment here + both draft PRs; PM subscribes to each PR the moment it exists.

---

Generated by Claude Code