| name | x-ipe-knowledge-constructor-user-manual |
| description | Domain expert for user manual construction. Provides framework, rubric, knowledge gap analysis, and structure filling via a 4-operation interface. Triggers on operations like "provide_framework", "design_rubric", "request_knowledge", "fill_structure". |
Constructor User Manual — Knowledge Skill
Purpose
AI Agents follow this skill to perform user manual construction operations:
- Provide a domain-appropriate framework (8-section layout with app-type mixins)
- Design measurable rubric criteria per framework section
- Identify knowledge gaps and generate extraction requests
- Fill the framework structure with gathered knowledge into a completed draft
Important Notes
BLOCKING: Operations are stateless services — the assistant orchestrator passes full context per call. Do NOT maintain internal state across operations.
CRITICAL: Each operation MUST define typed input/output contracts with a writes_to field.
CRITICAL: This skill is NOT directly task-matched. It is called by the Knowledge Librarian assistant (x-ipe-assistant-knowledge-librarian-DAO) or another assistant orchestrator.
CRITICAL: This skill writes ONLY to .working/ paths. Promotion to persistent memory is handled by x-ipe-knowledge-keeper-memory.
About
This skill serves as the domain expert for user manual construction. It knows the structure of user manuals (8 standard sections), the quality criteria for each section, and what knowledge is needed to fill them. The Knowledge Librarian orchestrator calls its 4 operations in sequence to drive the construction pipeline.
Key Concepts:
- Operation Contract — Each operation declares its input types, output types, writes_to path, and constraints. The orchestrator uses this contract to plan execution.
- Stateless Service — The skill receives all needed context from the orchestrator per call. No cross-operation memory.
- writes_to Discipline — Every operation writes to
x-ipe-docs/memory/.working/{subpath}/ only. No persistent writes.
- Domain Templates — 6 templates in
templates/ define the user manual structure, extraction prompts, rubric criteria, and app-type overlays.
- 8-Section Layout — Standard user manual sections: Overview, Installation & Setup, Getting Started, Core Features, Common Workflows, Configuration, Troubleshooting, FAQ & Reference.
When to Use
triggers:
- "Provide a user manual framework for an application"
- "Design quality rubric for a user manual"
- "Identify knowledge gaps in a user manual draft"
- "Fill user manual structure with gathered knowledge"
not_for:
- "Orchestration decisions (belongs to x-ipe-assistant-knowledge-librarian-DAO)"
- "Extracting knowledge from web or memory (belongs to extractor skills)"
- "Persisting finished drafts (belongs to x-ipe-knowledge-keeper-memory)"
- "Ontology registration (belongs to x-ipe-knowledge-ontology-builder)"
Input Parameters
input:
operation: "provide_framework | design_rubric | request_knowledge | fill_structure"
context:
request_context:
app_name: "string"
app_type: "web | cli | mobile"
user_goal: "string"
source_paths: "string[]"
output_format: "markdown | split"
framework: "dict"
overview: "string"
user_request: "string"
framework: "dict"
current_state: "dict"
rubric: "dict"
framework: "dict"
gathered_knowledge: "object[]"
rubric: "dict"
Input Initialization
BLOCKING: All input fields with non-trivial initialization MUST be documented here.
<input_init>
<field name="operation" source="Assistant orchestrator specifies which operation to perform">
<validation>Must be one of: provide_framework, design_rubric, request_knowledge, fill_structure</validation>
</field>
<field name="context.request_context" source="Required for provide_framework">
<validation>Must contain app_name, app_type, user_goal, source_paths[]</validation>
</field>
<field name="context.request_context.app_type" source="Determines which mixin template to apply">
<validation>Must be one of: web, cli, mobile</validation>
</field>
<field name="context.framework" source="Required for design_rubric, request_knowledge, fill_structure">
<validation>Must be a valid framework_document from provide_framework</validation>
</field>
<field name="context.rubric" =>
Must be a valid rubric from design_rubric
Array of {section_id, content, source, metadata} objects
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Operation specified</name>
<verification>input.operation matches one of the 4 defined operations</verification>
</checkpoint>
<checkpoint required="true">
<name>Operation-specific context provided</name>
<verification>All required context fields for the specified operation are present</verification>
</checkpoint>
<checkpoint required="true">
<name>Working directory accessible</name>
<verification>x-ipe-docs/memory/.working/ exists and is writable</verification>
</checkpoint>
</definition_of_ready>
Operations
Operation: provide_framework
Contract:
- Input: request_context: {app_name: string, app_type: "web"|"cli"|"mobile", user_goal: string, source_paths: string[]}, output_format: "markdown"|"split"
- Output: framework_document: dict, toc_structure: {id: string, title: string, stubs: string, depth: number}[]
- Writes To: x-ipe-docs/memory/.working/framework/
- Constraints: Load playbook-template.md; select mixin by app_type; adapt to request_context; return framework with section stubs
When: Orchestrator needs a structured user manual outline tailored to the target application.
<operation name="provide_framework">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: request_context (app_name, app_type, user_goal, source_paths[]), output_format
2. LOAD templates/playbook-template.md as the base 8-section layout
3. DETERMINE which mixin to apply based on app_type:
- web → LOAD templates/mixin-web.md
- cli → LOAD templates/mixin-cli.md
- mobile → LOAD templates/mixin-mobile.md
</action>
<output>Base template and mixin loaded, request context understood</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE app_type is one of: web, cli, mobile
2. VALIDATE app_name is non-empty
3. VALIDATE source_paths[] is non-empty array
4. CHECK output_format defaults to "markdown" if not specified
</action>
<constraints>
- BLOCKING: Invalid app_type → return error INVALID_APP_TYPE
- BLOCKING: Missing app_name → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Input validated, template selection confirmed</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. MERGE mixin sections into base playbook template:
- Insert mixin Additional Sections at specified positions
- Apply mixin Section Overlay Prompts to augment existing sections
2. ADAPT section titles and stubs to request_context:
- Replace {App Name} placeholders with app_name
- Tailor subsection guidance to user_goal
3. BUILD toc_structure array with {id, title, stubs, depth} per section
4. FORMAT as output_format (inline markdown or split file references)
framework_document with adapted sections, toc_structure array
1. VERIFY framework contains all 8 base sections plus mixin additions
2. VERIFY toc_structure entries match framework sections
3. VERIFY no {placeholder} tokens remain unresolved
4. IF any check fails → return error with details
Output validated
1. WRITE framework_document to x-ipe-docs/memory/.working/framework/{app_name}-framework.md
2. RETURN operation_output:
- success: true
- operation: "provide_framework"
- result: { framework_document, toc_structure }
- writes_to: "x-ipe-docs/memory/.working/framework/"
- errors: []
Framework written, result returned to orchestrator
Operation: design_rubric
Contract:
- Input: framework: dict, overview: string, user_request: string
- Output: rubric_metrics: {section_id: string, criteria: string, weight: number, threshold: string}[], acceptance_criteria: {section_id: string, checks: string[]}[]
- Writes To: x-ipe-docs/memory/.working/rubric/
- Constraints: Load acceptance-criteria.md; define measurable criteria per section; weight by user emphasis
When: Orchestrator needs measurable quality criteria to evaluate extracted knowledge.
<operation name="design_rubric">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework (from provide_framework), overview, user_request
2. LOAD templates/acceptance-criteria.md as base rubric definitions
3. IDENTIFY which sections the user emphasizes in user_request
</action>
<output>Framework sections and base criteria loaded, user priorities identified</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework is a valid framework_document (has sections)
2. VALIDATE overview is non-empty
3. VALIDATE user_request is non-empty
</action>
<constraints>
- BLOCKING: Invalid or empty framework → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Input validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. FOR EACH section in framework:
a. MAP [REQ] items from acceptance-criteria.md to measurable rubric_metrics
b. SET weight based on user emphasis (high=3, normal=2, low=1)
c. SET threshold from acceptance criteria (e.g., "≥3 features documented")
d. COMPILE acceptance_criteria checks from [REQ] + [OPT] items
2. ADJUST weights: sections explicitly mentioned in user_request get weight=3
3. ENSURE all rubric_metrics have numeric weight and testable threshold
rubric_metrics[] and acceptance_criteria[] per section
1. VERIFY every framework section has at least one rubric_metric entry
2. VERIFY weights are numeric (1-3 range)
3. VERIFY thresholds are testable (not vague)
4. IF any check fails → return error with details
Output validated
1. WRITE rubric to x-ipe-docs/memory/.working/rubric/{app_name}-rubric.md
2. RETURN operation_output:
- success: true
- operation: "design_rubric"
- result: { rubric_metrics, acceptance_criteria }
- writes_to: "x-ipe-docs/memory/.working/rubric/"
- errors: []
Rubric written, result returned to orchestrator
Operation: request_knowledge
Contract:
- Input: framework: dict, current_state: {filled_sections: string[], empty_sections: string[], partial_sections: string[]}, rubric: dict
- Output: knowledge_requests: {target_section: string, what_needed: string, suggested_extractor: "extractor-web"|"extractor-memory", priority: number}[]
- Writes To: x-ipe-docs/memory/.working/plan/
- Constraints: Walk framework sections; compare to current_state; generate specific requests per gap; set suggested_extractor; prioritize by rubric weight; return empty array if no gaps
When: Orchestrator needs to know what knowledge to gather next.
<operation name="request_knowledge">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework, current_state, rubric
2. LOAD templates/collection-template.md for per-section extraction prompt patterns
3. BUILD section inventory from framework toc_structure
</action>
<output>Framework sections, current state, and extraction prompts loaded</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework has sections
2. VALIDATE current_state has filled_sections, empty_sections, partial_sections
3. VALIDATE rubric has metrics for each section
</action>
<constraints>
- BLOCKING: Missing current_state → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Input validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. FOR EACH section in framework:
a. IF section in current_state.filled_sections → SKIP
b. IF section in empty_sections or partial_sections:
- READ extraction prompts from collection-template.md for this section
- GENERATE specific what_needed description (not vague)
- SET suggested_extractor:
* "extractor-web" for content needing live source analysis (code, UI, API)
* "extractor-memory" for content that may exist in existing knowledge base
- SET priority from rubric weight (higher weight = higher priority)
- ADD to knowledge_requests[]
2. SORT knowledge_requests by priority descending
3. IF no gaps found → return empty knowledge_requests[]
knowledge_requests[] with targeted extraction requests
1. VERIFY each request has target_section, what_needed, suggested_extractor, priority
2. VERIFY suggested_extractor is "extractor-web" or "extractor-memory"
3. VERIFY what_needed is specific (not "get more info")
4. IF any check fails → return error with details
Output validated
1. WRITE plan to x-ipe-docs/memory/.working/plan/{app_name}-plan.md
2. RETURN operation_output:
- success: true
- operation: "request_knowledge"
- result: { knowledge_requests }
- writes_to: "x-ipe-docs/memory/.working/plan/"
- errors: []
Plan written, result returned to orchestrator
Operation: fill_structure
Contract:
- Input: framework: dict, gathered_knowledge: {section_id: string, content: string, source: string, metadata: dict}[], rubric: dict
- Output: completed_draft: string
- Writes To: x-ipe-docs/memory/.working/draft/
- Constraints: Map gathered knowledge to framework sections; mark incomplete sections with [INCOMPLETE: reason]; validate against rubric; do NOT write to persistent memory
When: Orchestrator has gathered knowledge and needs it assembled into the user manual structure.
<operation name="fill_structure">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework, gathered_knowledge[], rubric
2. INDEX gathered_knowledge by section_id for fast lookup
3. LOAD framework toc_structure for section ordering
</action>
<output>Knowledge indexed, framework structure loaded</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework has sections
2. VALIDATE gathered_knowledge is non-empty array with section_id and content
3. VALIDATE rubric has acceptance_criteria for evaluation
</action>
<constraints>
- BLOCKING: Empty gathered_knowledge → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Input validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. FOR EACH section in framework (ordered by toc_structure):
a. FIND matching entries in gathered_knowledge by section_id
b. IF content found:
- MAP content into the section template from playbook-template.md
- VALIDATE against rubric acceptance_criteria for this section
- IF rubric threshold NOT met → append [INCOMPLETE: {specific reason}]
c. IF no content found:
- INSERT section stub with [INCOMPLETE: No knowledge gathered for this section]
2. ASSEMBLE completed_draft following playbook-template.md structure
3. ADD Table of Contents at top with section links
completed_draft with all sections mapped
1. VERIFY completed_draft contains all framework sections
2. VERIFY incomplete sections are marked with [INCOMPLETE: reason]
3. VERIFY Table of Contents links match actual sections
4. COUNT completeness: sections_complete / total_sections
5. IF any structural check fails → return error with details
Output validated, completeness score calculated
1. WRITE draft to x-ipe-docs/memory/.working/draft/{app_name}-user-manual.md
2. RETURN operation_output:
- success: true
- operation: "fill_structure"
- result: { completed_draft, completeness_score }
- writes_to: "x-ipe-docs/memory/.working/draft/"
- errors: []
Draft written, result returned to orchestrator
Output Result
operation_output:
success: true | false
operation: "provide_framework | design_rubric | request_knowledge | fill_structure"
result:
framework_document: "dict"
toc_structure: "object[]"
rubric_metrics: "object[]"
acceptance_criteria: "object[]"
knowledge_requests: "object[]"
completed_draft: "string"
completeness_score: "number"
writes_to: "x-ipe-docs/memory/.working/{subpath}/"
errors: []
Definition of Done
<definition_of_done>
<checkpoint required="true">
<name>Operation completed successfully</name>
<verification>operation_output.success == true</verification>
</checkpoint>
<checkpoint required="true">
<name>Output written to declared .working/ path</name>
<verification>File exists at writes_to path with expected content</verification>
</checkpoint>
<checkpoint required="true">
<name>Output matches contract types</name>
<verification>Returned data matches the operation's declared output types</verification>
</checkpoint>
<checkpoint required="true">
<name>No persistent writes</name>
<verification>No files written outside x-ipe-docs/memory/.working/</verification>
Error Handling
| Error | Cause | Resolution |
|---|
INVALID_OPERATION | Operation name not one of the 4 defined | Return error listing valid operations |
INVALID_APP_TYPE | app_type not web/cli/mobile (provide_framework) | Return error listing valid types |
INPUT_VALIDATION_FAILED | Required input missing or wrong type | Return error with specific field and expected type |
TEMPLATE_NOT_FOUND | Domain template file missing from templates/ | Return error with expected template path |
WRITE_FAILED | Cannot write to .working/ path | Return error; orchestrator decides retry or alternate path |
QUALITY_THRESHOLD_NOT_MET | Output below rubric quality bar | Return partial results with quality metrics; orchestrator decides |
Patterns & Anti-Patterns
| Pattern | When | Key Actions |
|---|
| Incremental fill | Large knowledge base | Fill sections iteratively, validate rubric after each pass |
| Mixin composition | Multi-platform app | Stack platform mixins (web+mobile) in provide_framework |
| Gap-first planning | Cold start | Run request_knowledge before any extraction to prioritize |
| Anti-Pattern | Why Bad | Do Instead |
|---|
| Skip rubric | No quality gate | Always design_rubric before fill_structure |
| Persist from constructor | Bypasses librarian | Write to .working/ only; let librarian promote |
| Monolithic fill | Hard to iterate | Fill per-section, validate incrementally |
Examples
See references/examples.md for worked examples of each operation.
