ccpe-system/skills/workflow/evidence-routing-and-topic-doc-builder.skill.md

artifact_type	name	skill_id	author	version	created	updated	status	skill_type	target_platform	based_on	related_models	related_agents	related_runtimes	related_protocols
ccpe-skill	evidence-routing-and-topic-doc-builder	evidence-routing-and-topic-doc-builder	CCPE System	0.2	2026-06-06	2026-06-07	draft	workflow-skill / knowledge-management-skill / transformation-skill	Codex / Claude Code / OpenClaw / platform-neutral Markdown	CCPE System	candidate lossless-viewpoint-distillation	topic-discovery-router topic-graph-synthesizer lossless-coverage-auditor	viewpoint-discussion-distillation	agent-invocation-packet

Evidence Routing And Topic Doc Builder Skill

1. Skill Overview

1.1 Purpose

Build material-unit extraction records, routing logs, and topic documents from a confirmed topic graph while preserving source material, routing rationale, structured viewpoint layers, and downstream task candidates.

This Skill must not run before Gate 3 confirms or repairs the topic graph.

1.2 Skill Type

workflow-skill
knowledge-management-skill
transformation-skill

1.3 Intended Users

Viewpoint Discussion Distillation Runtime after Topic Graph Synthesizer and Gate 3.

When executed by a Runtime operator as a formal Skill execution, this Skill requires a Skill execution record under the Agent Invocation Packet Protocol. If substantial source reading or extraction is required, worker/sub-session execution is preferred unless the local Skill execution record fully documents the procedure.

1.4 Success Criteria

- Confirmed topic graph is present before routing starts.
- Material-unit extraction records explain which source units were extracted and where they were placed.
- Routing log explains primary and secondary topic placement.
- Topic documents include source material layer.
- Structured interpretation does not replace source material.
- Many-to-many routing is explicit.
- Downstream task candidates are recorded without forcing execution.
- Gate 6 can inspect whether extracted material is useful enough for downstream automation.

2. Trigger Conditions

Use this Skill when:

- Gate 3 has confirmed or repaired the topic graph.
- Source blocks need to be placed into topic documents.
- Topic documents need a consistent Knowledge Vault structure.
- Material-unit extraction records are required before Gate 6.

Do not use this Skill when:

- Source blocks do not exist.
- Topic graph is unconfirmed or hierarchy repair is pending.
- The user has not confirmed the output workspace.
- The Runtime is still waiting for Whole-Source Gestalt Reviewer, Topic Discovery Router, or Topic Graph Synthesizer returned output.

3. Input Contract

3.1 Required Inputs

- 00-source-map.md
- confirmed 01-topic-map.md or accepted topic graph returned-output.md
- Gate 3 confirmation / hierarchy repair record
- source block content or accessible source document
- output_workspace_path
- source_primary_language
- output_language_policy: mirror_source_primary_language
- invocation packet or Skill execution context

3.2 Optional Inputs

- accepted Step 0 lens
- topic-discovery worker returns
- user-confirmed topic renames
- downstream task hints
- existing topic documents to update
- routing confidence threshold

3.3 Input Quality Requirements

Topic graph must include topic IDs or slugs and routing readiness status. Source blocks must be recoverable from source-map or source document. If Gate 3 is missing, abort before writing routing or topic docs.

4. Output Contract

4.1 Output Types

- material-unit extraction records
- 02-material-routing-log.md
- topics/{topic-slug}.md
- handoff/downstream-task-routing.md draft only if requested after Gate 6 and audit readiness

4.2 Material-Unit Extraction Record Format

# Material Unit Extraction Records

## 1. Extraction Metadata

## 2. Confirmed Topic Graph Reference

## 3. Source Blocks Processed

| material_unit_id | source_block_ids | source_locator | primary_topic | secondary_topics | extraction_type | confidence | notes |

## 4. Low-Confidence Units

## 5. Units Needing Human Review

4.3 Topic Document Format

# {Topic Name}

## 1. Status

## 2. Scope

## 3. Source Material Layer

## 4. Structured Viewpoint Layer

## 5. Models / Mechanisms

## 6. Practices / Examples

## 7. Downstream Task Candidates

## 8. Open Questions

## 9. Links To Other Topics

## 10. Source Index

## 11. Material Unit Index

4.4 Output Quality Requirements

Every source-derived claim in structured layers must trace to one or more source block IDs and material unit IDs. The source material layer must not be omitted. Because material-unit records, routing logs, and topic docs feed Gate 6, their human-review sections must use the source material's primary language as the dominant language. English may remain in slugs, IDs, paths, and secondary aliases.

5. Model Context

5.1 Related Model Cards

- model_id: none
  model_card_path: none

5.2 Model Fidelity Rules

Preserve user terminology, metaphor, conceptual tension, examples, and practical details. Do not flatten material into generic productivity categories.

6. Procedure

6.1 Main Procedure

1. Verify confirmed topic graph and Gate 3 record.
2. Verify source-map, source block recoverability, output workspace, and execution record requirement.
3. Load source-map and confirmed topic graph.
4. For each source block, extract one or more material units.
5. Assign material_unit_id and preserve source block IDs.
6. Route material units to primary and secondary topics using the confirmed topic graph.
7. Write material-unit extraction records.
8. Write material-routing-log with topic placement, rationale, and confidence.
9. Create or update topic documents.
10. Insert source material layer with source block IDs and material unit IDs.
11. Add structured viewpoint layer derived from source material.
12. Record models, mechanisms, practices, examples, downstream candidates, and open questions.
13. Add source index, material unit index, and cross-topic links.
14. Write Skill execution record when executed locally as formal Runtime work.

6.2 Branch Logic

- If Gate 3 is missing or hierarchy repair is pending, abort before writing.
- If a block belongs to multiple topics, assign primary and secondary routes.
- If a block contains multiple separable ideas, split into multiple material units.
- If a block is mostly task-oriented, record it under downstream task candidates.
- If a block is an unresolved question, keep it in Open Questions instead of confirmed facts.
- If a topic doc becomes too broad, flag split candidate for the topic graph layer rather than silently restructuring.
- If source-heavy extraction is too large for current session, create worker/sub-session packets and block until returned output exists.

6.3 Stop Conditions

Complete when material-unit records, routing log, and topic docs are written for all routed source blocks, or when unclear routing is explicitly placed in a low-confidence queue for Gate 6 review.

6.4 Fallback Procedure

If routing is unclear, place the material unit in a low-confidence section and mark for human review. Do not invent hierarchy beyond the confirmed graph.

7. Tool Layer

7.1 Tools Used

- tool_name: filesystem
  purpose: read source-map/topic-graph/source blocks and write extraction records/routing logs/topic docs
  trigger: after Gate 3
  input: confirmed workspace and confirmed topic graph
  output: material-unit records, routing log, topic docs, Skill execution record when formal local execution

7.2 Tool Permission

Write only inside confirmed output workspace. Do not alter original source.

7.3 Tool Failure Handling

Stop and report missing source-map, confirmed topic graph, Gate 3 record, source content, output path, or execution record path.

8. Authority Layer

8.1 Autonomous Actions

- Create draft material-unit extraction records.
- Create draft topic documents.
- Add source material and structured layers.
- Mark downstream candidates.
- Mark low-confidence routing.

8.2 Actions Requiring Confirmation

- Finalize topic document set.
- Delete or merge topic docs.
- Generate specialized downstream packets.
- Treat topic docs as replacing the source.
- Accept topic docs as useful enough for downstream automation at Gate 6.

8.3 Forbidden Actions

- Run before confirmed topic graph / Gate 3.
- Omit source material layer.
- Omit material-unit records.
- Convert unresolved questions into facts.
- Remove source block IDs.
- Start downstream tasks.
- Simulate returned worker output or topic graph synthesis.

9. Constraints

9.1 Hard Constraints

- Confirmed topic graph is required.
- All routed material must be traceable to source block IDs and material unit IDs.
- Source material and structured interpretation must be separated.
- Low-confidence routing must remain visible.
- Formal local execution requires skill-execution-record.md.
- Main session may integrate returned outputs only; it must not create formal topic docs by simulation.

9.2 Soft Constraints

Prefer topic docs that are useful for future reading without becoming bloated.

9.3 Refusal / Abort Conditions

Abort if source block content cannot be recovered, Gate 3 is absent, topic graph is unconfirmed, or the task asks for formal output without valid execution record.

10. Evaluation

10.1 Validation Checklist

Confirmed topic graph present?
Gate 3 record present?
Inputs satisfied?
Procedure followed?
Material-unit records present?
Source material layer present?
Source block IDs preserved?
Material unit IDs preserved?
Output meets contract?
Skill execution record present when required?
Failure modes handled?
Gate 6 review possible?
Gate 6 human-review language mirrors source primary language?

10.2 Failure Modes

Summary-only docs, missing source IDs, missing material-unit records, topic sprawl, writing bias, unresolved questions mixed into conclusions, routing before hierarchy acceptance.

10.3 Test Cases

Test Case 1:
Input: source-map plus confirmed topic graph with one block routed to two topics.
Expected Output: material unit record with primary and secondary routing; both topic docs trace the source ID and material unit ID.

Test Case 2:
Input: source block describing a future system build.
Expected Output: topic doc records system/engineering downstream candidate, not writing-only direction.

Test Case 3:
Input: source-map plus unconfirmed topic graph.
Expected Output: blocked before `02-material-routing-log.md` or `topics/*.md` are written.

11. Runtime Integration

11.1 Used By Agents

- topic-graph-synthesizer
- lossless-coverage-auditor

11.2 Used By Runtimes

- viewpoint-discussion-distillation

11.3 Handoff Output

Hand off material-unit records, routing log, topic documents, and downstream candidate sections to Gate 6 and the auditor.

Required execution record when executed locally:

invocations/evidence-routing-and-topic-doc-builder/skill-execution-record.md

12. Platform Implementation Notes

12.1 Codex

Use file writes through confirmed paths. Keep generated documents in Knowledge Vault, not CCPE System.

12.2 Claude Code

Use the same Markdown structure and approval gates.

12.3 OpenClaw

Use file-backed state and explicit handoffs.

12.4 Platform-Neutral

The skill can be implemented manually by following the confirmed topic graph, material-unit schema, routing log, and topic doc schema.

13. Version Notes

v0.2:
- Added confirmed topic graph prerequisite, material-unit extraction records, Gate 6 readiness support, and no-simulation boundary for formal topic docs.

v0.1:
- Initial draft.