docs: optimize skill files — dedup prose, add TOCs, sync SPEC mirrors

docs/specs/skills/SPEC-_generation.md

@@ -6,6 +6,8 @@ Shared artifact generation procedures used by five skills across two consumer gr
 
 This is an internal partial (`user-invocable: false`) — never invoked directly. Skills load it via `helpers: [_generation]` frontmatter.
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to `_generation.md` (structural check, file >100 lines); no prose trimmed and no behavioral change (Flow unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-_intake.md

@@ -25,6 +25,8 @@ This is the **only** behavioral fork in intake creation, and it is legitimately
 
 This is an internal partial (`user-invocable: false`, `disable-model-invocation: true`, `metadata: internal: true`) — never invoked directly. Canonical source is the flat `src/kit/skills/_intake.md`; `fab sync` deploys it to `.claude/skills/_intake/SKILL.md`.
 
+**Prose optimization** (260620-skop): a single-entry `## Contents` TOC added to `_intake.md` (structural check, file >100 lines, applied mechanically though the file has one `##` section); no prose trimmed and no behavioral change (Flow unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-_pipeline.md

@@ -15,6 +15,8 @@ A third value, **`{max_cycles}`**, is defined by the bracket itself (260612-c5tr
 
 This is an internal partial (`user-invocable: false`) — never invoked directly. Drivers declare it via `helpers: [_pipeline]` frontmatter.
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to `_pipeline.md` (structural check, file >100 lines); no prose trimmed and no behavioral change (Per-Cycle Rework Choreography / Flow unchanged).
+
 ## Per-Cycle Rework Choreography (f071)
 
 Stated exactly once, in the Auto-Rework Loop. Every cycle (the initial Step 2 failure and each later re-review failure alike):

docs/specs/skills/SPEC-_preamble.md

@@ -1,11 +1,19 @@
 # _preamble
 
+## Contents
+
+- Summary
+- Subsection Inventory
+- Flow
+
 ## Summary
 
 Shared context preamble loaded by every Fab skill. Defines path conventions, context loading layers (always-load — descriptive, with a skill-file-wins override and a derived, never-enumerated exception set; change context; memory lookup; source code), the **Skill Helper Declaration** frontmatter convention (including stage-conditional in-body loading), inlined **Naming Conventions**, inlined **Run-Kit (rk) Reference**, the **Common fab Commands** headline table, the next-steps convention (with a skill-file-declared ending opt-out) with state table, a pointer to the skill invocation protocol (defined in `fab-clarify.md` since 260611-zc9m), subagent dispatch pattern with standard subagent context and **Per-Stage Model Resolution** (260613-l3ja — `fab resolve-agent <stage>` before each pipeline-stage dispatch; resolved model+effort passed to the Agent dispatch with empty ⇒ omit/inherit; review resolves once for both reviewers + merge; per-stage selection applies on every post-intake stage — every post-intake stage now dispatches a sub-agent (including plain `/fab-continue` as a one-stage sequencer), so `fab resolve-agent` applies uniformly across apply/review/hydrate, with the residual advisory case narrowed to a stage skill genuinely run with no dispatch at all (260613-fgxx); **the two halves dispatch through two seams (260613-m3d4)** — model via the Agent tool `model` param (a hard enum of short aliases `opus`/`sonnet`/`haiku`/`fable`, resolved with `fab resolve-agent <stage> --alias` so the alias is emitted directly — the deterministic Agent-tool adapter that replaced the earlier prompt-side id→alias hand-mapping; 260613-yky7) and effort via an explicit imperative instruction in the subagent prompt (the Agent tool has no effort param; omitted when empty), plus a **compliance-visibility** expectation that each site surface the resolved `model=/effort=` so a skipped/mis-resolved tier is visible rather than silent; resolution itself stays provider-neutral; the lone residual is a first-class per-sub-agent effort param on the Agent tool — a harness ask outside fab's control), a pointer to the SRAD autonomy framework (extracted to `_srad.md` in 260611-zc9m), and slimmed confidence scoring (gate threshold + invocation; schema/formula/template moved to `_cli-fab.md` § fab score).
 
 This is an internal partial (`user-invocable: false`) — it is never invoked directly. Skills reference it via the opening instruction: "Read the `_preamble` skill first (deployed to `.claude/skills/` via `fab sync`). Then follow its instructions before proceeding."
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to `_preamble.md` (structural check, file >100 lines); no prose trimmed and no behavioral change (Flow / Subsection Inventory unchanged). This SPEC also received a `## Contents` block under the same structural check.
+
 ## Subsection Inventory
 
 Post-260418-or0o, `_preamble.md` contains four additional subsections inlined from previously-separate helpers or lifted out of `_cli-fab.md`. Each is a canonical source within `_preamble`:

docs/specs/skills/SPEC-_review.md

@@ -1,5 +1,10 @@
 # _review
 
+## Contents
+
+- Summary
+- Flow
+
 ## Summary
 
 Shared review dispatch logic invoked by `/fab-continue`, `/fab-ff`, and `/fab-fff` at the review stage. Defines the inward sub-agent (validates implementation against `plan.md`'s `## Requirements`, `## Tasks`, and `## Acceptance` with eight validation checks, including the parsimony pass and deletion-candidate prompt) and the outward sub-agent (Codex→Claude cascade with full repo access for holistic diff review). Both sub-agents are dispatched in parallel; their findings are merged into a single prioritized set with three severity tiers.
@@ -8,6 +13,8 @@ This is an internal partial (`user-invocable: false`) — it is never invoked di
 
 The rework loop is NOT defined here — the file's trailing note points at the orchestrators: `fab-continue.md`'s Verdict section for manual rework, and `_pipeline.md` § Auto-Rework Loop for `/fab-ff`/`/fab-fff` (pointer corrected in 260611-szxd; it previously cited "fab-ff.md/fab-fff.md Step 3").
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to `_review.md` (structural check, file >100 lines); no prose trimmed and no behavioral change (Flow unchanged). This SPEC also received a `## Contents` block under the same structural check.
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-_srad.md

@@ -6,6 +6,8 @@ SRAD autonomy framework helper — the decision framework planning skills apply
 
 Extracted from `_preamble.md` § SRAD Autonomy Framework in 260611-zc9m (the preamble keeps a 3-line pointer). This is an internal partial (`user-invocable: false`) — never invoked directly. It is loaded via the frontmatter `helpers:` list of the six planning skills: `fab-new`, `fab-draft`, `fab-continue`, `fab-ff`, `fab-fff`, `fab-clarify`. Non-planning skills do not load it.
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to `_srad.md` (structural check, file >100 lines); no prose trimmed and no behavioral change (Flow unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-docs-hydrate-memory.md

@@ -16,6 +16,8 @@ Distinct from generate mode (which *creates* files from source-code gaps), backf
 - **Caller-aware regen**: when dispatched by reorg (defer-regen signal in the prompt), it does NOT run `fab memory-index` (reorg runs it once at the end); when invoked directly, it runs `fab memory-index` as the final step like the other modes.
 - **Scope**: pure frontmatter operation — does NOT detect/relocate tombstone rows, flatten groupings, move files, or strip existing `## Changelog` bodies; those structural concerns belong to `/docs-reorg-memory` (and the changelog strip to FKF Change 4).
 
+**Prose optimization** (260620-skop): skill content trimmed to remove re-explanation of partial-owned concepts (the `templates/memory.md` read + FKF frontmatter + no-`## Changelog` rule + shape bounds now stated once in ingest Step 3 and referenced from generate/backfill; refuse-before-regen guard and arg-classification reject strings compressed to pointers) and a `## Contents` TOC added; no behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-docs-hydrate-specs.md

@@ -4,6 +4,8 @@
 
 Reverse hydration: identifies gaps where memory covers topics that specs don't. Proposes concise additions to specs with per-gap user confirmation. Top 3 gaps ranked by impact. When no existing spec is a suitable home for a gap, it proposes a new `docs/specs/{kebab-topic}.md` under the same per-gap confirmation; on yes it creates the file and adds its `docs/specs/index.md` row — the one index edit the skill makes.
 
+**Prose optimization** (260620-skop): skill content trimmed (the Pre-flight index-existence checks compressed to one line while keeping both literal STOP strings, which the Error Handling rows reference) and a `## Contents` TOC added; the Step 6 token handler, the no-target/new-file branch, and the one-index-edit note are unchanged. No behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-docs-reorg-memory.md

@@ -4,6 +4,8 @@
 
 Analyzes memory files for themes and suggests reorganization. Read-only unless user approves changes. Identifies up to 10 themes, produces a **Shape Report** (folders over the ~12 width bound / over depth — folder depth >2, i.e. topic files past 3 path segments / under the ~5 floor; reserved domains `_shared`/`_unsorted` exempt), and proposes a reorg plan whose Migration Map `Kind` is one of `move-section` / `split-domain` / `merge-domain` / `flatten` / `move`. On approval it is the **memory rebalancer**: it performs the approved migrations, rewrites the **bundle-relative** links the moves break, preserves each moved file's FKF frontmatter, authors `description:` frontmatter (+ `type: memory`) on new files and creates each new sub-domain's `description:`-only index stub before `fab memory-index` runs, and regenerates indexes (and per-folder `log.md`) via `fab memory-index`. Index/log files (root, domain, and sub-domain tiers) are regenerated by `fab memory-index`, never hand-edited. It also **orchestrates a one-time compatibility migration** for pre-fab-kit memory trees (see below).
 
+**Prose optimization** (260620-skop): skill content trimmed to remove re-explanation of partial-owned concepts (the §7 bundle-relative payoff, the "reorg authors ONE mechanical file / synthesis lives in backfill" delegation, the older-binary fallback, and the "indexes are generated, not hand-authored" rule now stated once and referenced elsewhere) and a `## Contents` TOC added; no behavioral change — the 5-step apply, strict-order compatibility orchestration, no-dangling-link hard block, and decline=no-mutation logic are unchanged (Flow / Tools / Sub-agents unchanged).
+
 ## FKF-Aware Moves (`$(fab kit-path)/reference/fkf.md` §7)
 
 Memory↔memory links are **bundle-relative** (`](/{domain}[/{sub}]/{file}.md)`, resolved from `docs/memory/`), so a move's link blast radius is small: only links whose **bundle path changes** (links *to* a file that changes domain/sub-domain) need rewriting; a same-domain reshuffle that keeps files in the domain rewrites nothing — the §7 payoff ("reorg rewrites *far* fewer links"). Two invariants the move path enforces:

docs/specs/skills/SPEC-docs-reorg-specs.md

@@ -8,6 +8,8 @@ Analyzes spec files for themes and suggests reorganization. Read-only unless use
 
 **No FKF frontmatter on spec moves (specs are human-curated — a fab-kit design principle).** FKF (`type: memory` + `description:`) governs `docs/memory/` only; specs are out of FKF scope and stay frontmatter-free, human-curated per that **fab-kit design principle**. When the skill moves a spec file it MUST NOT stamp, add, or synthesize `type:` / `description:` frontmatter — a moved spec carries exactly its prior bytes (only its path and the `index.md` row change). This is the deliberate mirror of `docs-reorg-memory`'s frontmatter-*preserving* moves: memory moves keep FKF frontmatter, spec moves add none. A generated-index model for `docs/specs/index.md` is **not adopted** (specs are human-curated — a fab-kit design principle) — no `fab specs-index` generator; the specs index stays hand-rewritten and spec links stay ordinary repo-relative.
 
+**Prose optimization** (260620-skop): skill content trimmed — the three reserved-path / no-backfill / no-FKF blockquotes collapsed to one consolidated `### Reserved Paths` blockquote stating the human-curated principle plus its three rules, with Step 5 and the Key-Properties rows reduced to back-refs — and a `## Contents` TOC added; no behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-archive.md

@@ -8,6 +8,8 @@ Archives a completed change (post-hydrate) or restores an archived change. Deleg
 
 Since 260611-szxd (f087) the skill file is a **single document**: mode detection and both argument lists are stated once at the top; archive mode is the default body; restore-specific content lives in a `## Restore Mode` section holding only its unique Behavior/Output/Error-Handling/Key-Properties. The restore pre-flight is preserved as mode-specific content — it **waives** the standard preflight and the hydrate guard (opposite of archive mode; restore applies to any archived change regardless of state).
 
+**Prose optimization** (260620-skop): skill content trimmed to dedupe the dirty-tree disclosure (Key-Properties "Leaves uncommitted changes?" rows now reference the § Purpose blockquote) and to point the restore Step-1 error narration at § Error Handling, and a `## Contents` TOC added; no behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-clarify.md

@@ -6,6 +6,8 @@ Refines the intake artifact without advancing. Two modes: Suggest (interactive,
 
 **Helpers**: Declares `helpers: [_srad]` in frontmatter per `docs/specs/skills.md § Skill Helpers`.
 
+**Prose optimization** (260620-skop): skill content trimmed to remove re-explanation of partial-owned concepts — the post-intake/missing-intake STOP messages now point to the canonical Error Handling table, the re-grade-by-composite rule is stated once (Step 2's Artifact Update) and referenced from Step 4, the shared audit-trail placement/append rule is stated once and referenced, and the dormant "retained for future use" statement is consolidated to § Skill Invocation Protocol → Currently Applicable; a `## Contents` TOC added to the skill. No behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-continue.md

@@ -1,5 +1,10 @@
 # fab-continue
 
+## Contents
+
+- [Summary](#summary)
+- [Flow](#flow)
+
 ## Summary
 
 Advances through the 6-stage pipeline one step at a time. Each invocation handles the current stage's work and transitions to the next. Supports reset to a given stage (legacy `tasks`/`spec` targets error with a pointer to the `apply` and `intake` reset routes). Handles all six stages: intake (the only planning stage), apply (co-generates `plan.md` `## Requirements` + `## Tasks` + `## Acceptance` at entry then runs tasks), review (sub-agent), hydrate, ship (delegates to `/git-pr` behavior), and review-pr (delegates to `/git-pr-review` behavior).
@@ -14,6 +19,8 @@ Advances through the 6-stage pipeline one step at a time. Each invocation handle
 
 **FKF hydrate prose** (260615-8fr5, 260616-2fm8): Hydrate Behavior authors memory files to the FKF contract — the shipped normative extract at `$(fab kit-path)/reference/fkf.md` (260616-frlo; mirror of the dev-repo design doc `docs/specs/fkf.md`). New memory files are created from the canonical memory-file template shipped at `$(fab kit-path)/templates/memory.md` (260616-2fm8) — read on demand the same way `_generation.md`/`_intake.md` read `$(fab kit-path)/templates/intake.md` — the single source of truth for the FKF frontmatter pair — `type: memory` (constant, §3.1) plus a curated `description:` one-liner (§3.2) — and the body skeleton; not `description:` alone. Hydrate no longer writes a per-file `## Changelog` section (§3.3): it records what changed once via `fab status set-summary {change} "<one-line what-changed>"` (the C-lite `summary:` source line, §6.3, authored once at hydrate), which `fab memory-index` joins with git history to generate the per-folder `log.md` (§6). Memory↔memory cross-links use the bundle-relative `/...` form (§7); links out of the bundle stay repo-relative/absolute-URL. The "update existing" section list drops `Changelog` (now Requirements/Design Decisions only); the merge-without-duplication contract is unchanged. When hydrate edits an existing/legacy memory file missing `type: memory`, it stamps the constant in so the touched file becomes FKF-conforming (§2/§3.1 require `type: memory` on every memory file, stamped by every memory writer — not just on creation). This is FKF migration Change 3/4 — it stops *new* changelog writes; the strip of the 20 existing `## Changelog` sections is Change 4/4.
 
+**Prose optimization** (260620-skop): skill content trimmed to remove re-explanation of partial-owned concepts — the ~5 near-identical "dispatched block / sequencer owns transitions" blockquotes collapsed to one canonical statement (Normal Flow Step 1's dispatch contract) plus per-section references, the per-stage model paragraphs reduced to references, the Step 3 procedure table folded into prose, and Hydrate Step 4's long paragraph reformatted as a bullet list (same content); a `## Contents` TOC added to both the skill and this SPEC. No behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-fff.md

@@ -6,6 +6,8 @@ Full pipeline gated on the single intake gate (identical to fab-ff). Since 26061
 
 **Helpers**: Declares `helpers: [_generation, _review, _srad, _pipeline]` in frontmatter per `docs/specs/skills.md § Skill Helpers`.
 
+**Prose optimization** (260620-skop): skill content trimmed — the per-stage model recipe duplicated in the Step 4 and Step 5 preambles collapsed to one reference to the top-of-Behavior "Per-stage model" blockquote (matching `fab-ff.md`'s single-reference pattern), the Step 5 timeout outcome stated 3× reduced to one canonical literal in the Error Handling row (Step 5 and Output now reference it), and the synchronous-poll blockquote's rationale recap trimmed to a one-line pointer to `git-pr-review.md` while keeping the dispatch-seam MUST instruction itself; a `## Contents` TOC added. No behavioral change (Flow / Sub-agents / synchronous-poll directive / `{name}`-vs-`{id}` rule unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-new.md

@@ -12,6 +12,8 @@ Creates a new change from a natural language description, Linear ticket, or back
 
 **Helpers**: Declares `helpers: [_generation, _srad, _intake]` in frontmatter per `docs/specs/skills.md § Skill Helpers` (`_intake` added in 260613-3xaj; `_generation`/`_srad` kept declared directly, mirroring the `_pipeline` precedent where consumers declare underlying helpers alongside the orchestration helper).
 
+**Prose optimization** (260620-skop): a `## Contents` TOC added to the skill file (>100 lines); no content trimmed (the skill is already thin post-`_intake` extraction) and no behavioral change (Flow / Tools / Sub-agents unchanged).
+
 ## Flow
 
 ```

docs/specs/skills/SPEC-fab-operator.md

@@ -1,5 +1,17 @@
 # fab-operator
 
+## Contents
+
+- Summary
+- Section Structure
+- Primitives
+- Monitoring Tick
+- Watches (§7)
+- Auto-Nudge
+- Autopilot
+- Key Properties
+- Resolved Design Decisions
+
 ## Summary
 
 Standalone multi-agent coordination layer with proactive monitoring and auto-nudge. Runs in a dedicated tmux pane, observes all running fab agents across every session on its tmux server via `fab pane map --all-sessions`, routes commands via `tmux send-keys`, monitors progress via `/loop`, auto-answers routine agent questions, and drives autopilot queues through the full pipeline.
@@ -12,6 +24,8 @@ Not a lifecycle enforcer — the operator coordinates across agents and proxies
 
 **Helpers**: Declares `helpers: [_cli-fab, _cli-external]` in frontmatter per `docs/specs/skills.md § Skill Helpers`.
 
+**Prose optimization** (260620-skop): skill content trimmed to remove re-explanation of partial-owned concepts (launcher degraded behavior → `_cli-fab.md` § fab operator + §9; state-file path/migration → §2/§9; tick-step field semantics → `_cli-fab.md` § fab pane map; `rk notify` contract → `_cli-external.md` § rk + `_preamble.md` § Run-Kit; implicit `--base` chaining defined once in Queue ordering) and a `## Contents` TOC added; no behavioral change (Flow / Tools / Sub-agents unchanged). A `## Contents` TOC was also added to this SPEC (>100 lines, structural rule).
+
 ---
 
 ## Section Structure