394 lines
12 KiB
Markdown
394 lines
12 KiB
Markdown
---
|
|
artifact_type: ccpe-skill
|
|
name: evidence-routing-and-topic-doc-builder
|
|
skill_id: evidence-routing-and-topic-doc-builder
|
|
author: CCPE System
|
|
version: 0.2
|
|
created: 2026-06-06
|
|
updated: 2026-06-07
|
|
status: draft
|
|
skill_type: workflow-skill / knowledge-management-skill / transformation-skill
|
|
target_platform: Codex / Claude Code / OpenClaw / platform-neutral Markdown
|
|
based_on: CCPE System
|
|
related_models:
|
|
- candidate: lossless-viewpoint-distillation
|
|
related_agents:
|
|
- topic-discovery-router
|
|
- topic-graph-synthesizer
|
|
- lossless-coverage-auditor
|
|
related_runtimes:
|
|
- viewpoint-discussion-distillation
|
|
related_protocols:
|
|
- 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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```md
|
|
# 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
|
|
|
|
```md
|
|
# {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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
- topic-graph-synthesizer
|
|
- lossless-coverage-auditor
|
|
```
|
|
|
|
### 11.2 Used By Runtimes
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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.
|
|
```
|