knowledge-vault/skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md

# Runbook: Viewpoint Discussion Distillation

## 1. Before Creating A Work Directory

```text
1. Read Knowledge Vault README and VAULT rules.
2. Read this capability folder.
3. Read CCPE runtime handoff and invocation protocol.
4. Confirm target work directory with the user.
5. Confirm whether the source is likely under the high-context whole-source limit.
6. Confirm whether the first pass stops after source registration or proceeds to whole-source gestalt.
7. Choose invocation carriers before substantive processing.
8. Infer or confirm `source_primary_language` and set `output_language_policy: mirror_source_primary_language` for all human-review artifacts.
```

Strict invocation setup:

```text
- use Codex Thread for persistent Step 0 unless a resumable agent carrier is explicitly available
- record thread_id / agent_id in the invocation packet
- record source_primary_language, output_language_policy, human_confirmation_artifact, and gate_id_if_applicable
- do not accept packet-only or prompt-only stages as executed
- do not let the main session perform primary source analysis, routing, topic-doc drafting, or material extraction
- stop with blocked_waiting_for_participant_output when the required carrier is unavailable
```

## 2. First Pass: Source Registration

```text
1. Create the confirmed work directory.
2. Create required subdirectories.
3. Write README.md.
4. Write 00-source-map.md with source metadata and round boundaries.
5. Write 03-run-notes.md with decisions and gates.
6. Create invocation records for the whole-source gestalt reviewer when applicable.
7. Stop at the agreed confirmation point.
```

## 3. Step 0: Whole-Source Gestalt Alignment

Use this pass before segmentation when the source can fit inside a high-context participant.

Step 0 is not a one-shot summary. It is an alignment loop between the high-context participant and the user. The more accurate this pass is, the more automated the downstream work can be.

```text
1. Prepare a whole-source-gestalt-reviewer invocation packet.
2. Invoke a real high-context participant in a persistent sub-session; the main session must not perform this pass itself.
3. The participant reads the full source and first judges topic coherence.
4. If the source is coherent, output a global topic portrait, main structure, core tensions, model-evolution line, and hierarchy risks.
5. If the source is mixed, output macro-topic splits and say which parts require their own Step 0 pass.
6. If the source is fragmented, output a flat-topic discovery recommendation instead of forcing a hierarchy.
7. Save returned-output.md with source metadata and participant metadata.
8. Verify that the returned output's human-review language mirrors source_primary_language.
9. Ask the user to inspect and confirm, revise, or reject the Step 0 output only after the language check passes.
10. If the user corrects the structure or the language policy fails, send the correction back to the same Step 0 carrier and save the follow-up prompt and returned output.
11. Write or update 03-run-notes.md with the accepted gestalt output path and human confirmation status.
12. Stop if no real participant output is available.
```

Acceptance condition:

```text
Segmentation and worker topic extraction may proceed only after the run has either:
- a user-confirmed whole-source gestalt output;
- a user-confirmed macro-topic split plan; or
- a recorded exception explaining why the source cannot or should not receive a whole-source pass.
```

Downstream mode selection:

```text
coherent source -> structure-first mode; workers receive the confirmed global portrait as a required lens.
mixed source -> macro-topic mode; split first, then run Step 0 per macro-topic when needed.
fragmented source -> flat-discovery mode; workers should remain minimally biased and discover local topics.
```

## 4. Segmentation Pass

```text
1. Create worker thread-start packets by source range.
2. Include the confirmed whole-source gestalt summary and hierarchy cautions in each worker packet when the source is coherent.
3. If the source is fragmented, omit the structure lens and use unbiased flat-topic discovery.
4. Execute or dispatch conversation-segmentation.
5. Write skill-execution-record.md for local execution.
6. Collect source block indexes and worker return packets.
7. Create a continuation handoff before topic discovery.
```

Local Skill execution is valid only when the canonical Skill artifact is read and the execution record proves the procedure was followed. If segmentation is dispatched to workers, each worker must have a returned-output or thread-return packet.

## 5. Topic Discovery Pass

```text
1. Prepare topic-discovery-router invocation packet.
2. Provide the whole-source gestalt output as binding context, not as a final topic map.
3. Instruct workers to supplement and challenge the global portrait with local evidence, not rediscover the whole structure from zero.
4. Prepare prompt-to-send.md if the participant is external.
5. Stop if real invocation is unavailable.
6. Save returned output with metadata.
7. Draft 01-topic-map.md from accepted returned output.
8. Pause for user confirmation.
```

## 6. Topic Graph Synthesis And Human Confirmation

```text
1. Dispatch `topic-graph-synthesizer`, or write a synthesis-record that only integrates file-backed worker outputs.
2. Preserve distinctions among parent topic, subtopic, tool, layer, case, action track, and model upgrade.
3. Compare the synthesized hierarchy against the whole-source gestalt output.
4. Record unresolved hierarchy risks before routing.
5. Pause for user confirmation before material routing.
```

For coherent sources, the synthesizer receives the user-confirmed Step 0 lens and worker exceptions. It should not rediscover the structure from zero. Gate 3 human-review output must primarily use `source_primary_language`.

## 7. Evidence Routing And Topic Docs

```text
1. Confirm topic-map.
2. Assign each topic or topic group to an evidence-routing-and-topic-doc-builder worker/sub-session.
3. Give each worker the confirmed topic graph, assigned source ranges or source block IDs, required output schema, and Step 0 distortion guardrails.
4. Collect returned outputs or skill-execution records.
5. Write 02-material-routing-log.md from returned outputs.
6. Generate topic docs with source material layer, source index, and reusable material units from returned outputs.
7. The main session may integrate returned outputs, update indexes, and perform bounded verification; it should not do the primary extraction over source material when worker/sub-session execution is available.
8. Ask the user to inspect the topic docs / material extraction layer before downstream handoff.
9. If the user accepts the topic docs, record a Topic Docs Human Confirmation.
10. If the user corrects extraction or topic contents, run a repair pass or write an explicit human-correction record.
11. Do not declare completion until coverage audit is accepted.
```

Gate 6 occurs after topic docs and material extraction exist as worker/sub-session outputs. Gate 6 should answer whether the extracted material is useful enough for downstream automation and whether another worker repair pass is needed. Gate 6 human-review output must primarily use `source_primary_language`.

Topic Docs Human Confirmation should capture:

```text
- whether topic docs are structurally acceptable
- whether extracted material is useful enough for downstream automation
- whether another extraction pass is needed
- whether downstream work can proceed without another topic-granularity pause
```

## 8. Audit

```text
1. Prepare lossless-coverage-auditor invocation packet.
2. Save real returned output.
3. Write audits/coverage-audit.md and audits/distortion-risk-log.md.
4. Repair missing or distorted routing.
5. Ask user before any source-disposable claim.
```

## 9. Downstream Handoff

Create downstream packets only after user confirmation.

Possible downstream tracks:

```text
- writing-workbench
- CCPE model or participant work
- engineering project
- scale or rubric extraction
- todo extraction
- continued research
```