| name | x-ipe-knowledge-constructor-app-reverse-engineering |
| description | Domain expert for application reverse engineering reports. Provides framework scaffolding, rubric design, knowledge-gap analysis, and draft assembly via the 4-operation constructor interface. Triggers on operations like "provide_framework", "design_rubric", "request_knowledge", "fill_structure". |
Constructor App Reverse Engineering — Knowledge Skill
Purpose
AI Agents follow this skill to perform application reverse engineering report construction:
- Scaffold a domain framework mapping 8 RE sections to
x-ipe-tool-rev-eng-* sub-skills
- Design quality rubrics with measurable criteria per RE section
- Identify knowledge gaps and suggest extraction sub-skills to fill them
- Assemble gathered RE knowledge into a structured draft report
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 does NOT write to persistent memory — only to .working/ paths. Promotion to persistent memory is handled by x-ipe-knowledge-keeper-memory.
CRITICAL: This skill does NOT execute RE sub-skills. It generates extraction requests that reference them; the Librarian dispatches.
About
This skill serves as the domain expert for application reverse engineering reports. It understands the 8 standard RE sections, knows which x-ipe-tool-rev-eng-* sub-skill handles each section, and provides domain-specific templates (language mixins and repo-type mixins) for framework adaptation.
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 declares which
.working/ path it writes to, enabling the orchestrator to predict side effects and coordinate parallel operations.
- Section → Sub-Skill Mapping — Each of the 8 RE sections maps to a specific
x-ipe-tool-rev-eng-* sub-skill. This mapping drives both framework scaffolding and extraction planning.
- Mixin Composition — Templates are composed from a base playbook + language mixin + repo-type mixin, enabling cross-product coverage (e.g., Python × Microservices).
RE Section → Sub-Skill Map:
| # | Section | Sub-Skill |
|---|
| 1 | Architecture Recovery | x-ipe-tool-rev-eng-architecture-recovery |
| 2 | API Contract Extraction | x-ipe-tool-rev-eng-api-contract-extraction |
| 3 | Business Logic Mapping | x-ipe-tool-rev-eng-business-logic-mapping |
| 4 | Data Model Analysis | x-ipe-tool-rev-eng-data-model-analysis |
| 5 | Dependency Analysis | x-ipe-tool-rev-eng-dependency-analysis |
| 6 | Infrastructure Analysis | x-ipe-tool-rev-eng-infrastructure-analysis |
| 7 | Security & Auth Patterns | x-ipe-tool-rev-eng-security-auth-pattern |
| 8 | Testing Strategy | x-ipe-tool-rev-eng-testing-strategy |
When to Use
triggers:
- "Build an application reverse engineering report framework"
- "Design quality rubric for an RE report"
- "Identify knowledge gaps in a partially-filled RE report"
- "Assemble gathered RE knowledge into a structured draft"
not_for:
- "Orchestrating the full extraction pipeline (use x-ipe-assistant-knowledge-librarian-DAO)"
- "Executing actual code analysis (use x-ipe-tool-rev-eng-* sub-skills)"
- "Writing to persistent memory (use x-ipe-knowledge-keeper-memory)"
- "Web or memory search extraction (use extractor-web / extractor-memory)"
Input Parameters
input:
operation: "provide_framework | design_rubric | request_knowledge | fill_structure"
context:
request_context:
app_name: "string"
repo_path: "string"
language: "string"
repo_type: "string"
source_paths: "string[]"
output_format: "string"
framework: "dict"
overview: "string"
user_request: "string"
framework: "dict"
current_state: "dict"
rubric: "dict"
framework: "dict"
gathered_knowledge: "object[]"
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, repo_path, language, repo_type, source_paths[]</validation>
</field>
<field name="context.request_context.language" source="Detected or specified by orchestrator">
<validation>Supported: go, java, javascript, typescript, python. Unsupported languages use base playbook only</validation>
</field>
<field name="context.request_context.repo_type" source="Detected or specified by orchestrator">
<validation>Supported: single-module, multi-module, monorepo, microservices</validation>
</field>
<field name= =>
Must be a valid framework_document from provide_framework
Must be a valid rubric from design_rubric
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 present</name>
<verification>provide_framework: request_context present; design_rubric: framework+overview; request_knowledge: framework+current_state+rubric; fill_structure: framework+gathered_knowledge+rubric</verification>
</checkpoint>
<checkpoint required="true">
<name>Language/repo_type valid (provide_framework only)</name>
<verification>language and repo_type are recognized values or gracefully defaulted</verification>
</checkpoint>
</definition_of_ready>
Operations
Operation: provide_framework
Contract:
- Input: request_context: {app_name: string, repo_path: string, language: string, repo_type: string, source_paths: string[]}, output_format: string
- Output: framework_document: dict, toc_structure: {id: string, title: string, sub_skill: string, stubs: string[], depth: int}[]
- Writes To: x-ipe-docs/memory/.working/framework/
- Constraints: Load playbook-template.md; select language mixin + repo-type mixin; map all 8 sections to sub-skills; return framework with section stubs
When: Orchestrator needs a domain-specific framework for a new RE report.
<operation name="provide_framework">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: request_context (app_name, repo_path, language, repo_type, source_paths[])
2. LOAD base playbook from templates/playbook-template.md
3. IDENTIFY applicable mixins: language mixin (templates/mixin-{language}.md) + repo-type mixin (templates/mixin-{repo_type}.md)
</action>
<output>Base playbook loaded, applicable mixins identified</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE language is supported (go|java|javascript|typescript|python) — if not, skip language mixin
2. VALIDATE repo_type is supported (single-module|multi-module|monorepo|microservices) — if not, skip repo-type mixin
3. VALIDATE source_paths[] are non-empty
</action>
<constraints>
- BLOCKING: Empty source_paths → return error INPUT_VALIDATION_FAILED
- WARNING: Unsupported language → proceed with base playbook only, log warning
</constraints>
<output>Inputs validated, mixin selection confirmed</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. COMPOSE framework by merging: base playbook + language mixin overlays + repo-type mixin overlays
2. For each of the 8 RE sections, BUILD section stub with:
- Section title and subsection structure from playbook
- Mapped sub-skill name (from Section → Sub-Skill Map)
- Language-specific overlay prompts (from language mixin)
- Repo-type-specific overlay prompts and additional subsections (from repo-type mixin)
3. BUILD toc_structure[] with {id, title, sub_skill, stubs, depth} per section
4. ADAPT section emphasis based on request_context (e.g., microservices → weight inter-service sections higher)
Composed framework_document with 8 RE sections and toc_structure
1. VERIFY all 8 RE sections are present in framework_document
2. VERIFY each section maps to its correct x-ipe-tool-rev-eng-* sub-skill
3. VERIFY toc_structure has 8 entries
4. IF any verification fails → return error with details
Framework validated
1. WRITE framework_document to x-ipe-docs/memory/.working/framework/{app_name}-re-framework.md
2. RETURN operation_output with success, framework_document, toc_structure
Framework written and returned
Operation: design_rubric
Contract:
- Input: framework: dict, overview: string, user_request: string
- Output: rubric_metrics: {section_id: string, criteria: string, weight: float, threshold: string}[], acceptance_criteria: {section_id: string, checks: string[]}[]
- Writes To: x-ipe-docs/memory/.working/rubric/
- Constraints: Per-section measurable criteria; weight by user emphasis; higher weight = higher extraction priority
When: Orchestrator needs quality criteria for evaluating the RE report.
<operation name="design_rubric">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework (8 RE sections with sub-skill mappings), overview, user_request
2. UNDERSTAND user emphasis — which sections matter most (from user_request keywords)
3. GATHER section depth info from framework stubs
</action>
<output>Framework sections and user priorities understood</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework contains 8 RE sections
2. VALIDATE overview is non-empty
3. VALIDATE user_request is non-empty
</action>
<constraints>
- BLOCKING: Missing framework → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Inputs validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. For each RE section, DEFINE measurable criteria:
- Completeness: all subsections populated with substantive content
- Accuracy: claims backed by code citations (file:line)
- Depth: appropriate detail level for section type (e.g., architecture diagrams for section 1)
2. ASSIGN weights based on user emphasis (default: equal; emphasized sections get 1.5× weight)
3. BUILD rubric_metrics[] with {section_id, criteria, weight, threshold}
4. BUILD acceptance_criteria[] with {section_id, checks[]} — testable boolean checks per section
Rubric metrics and acceptance criteria defined
1. VERIFY rubric_metrics has entries for all 8 sections
2. VERIFY weights sum to a reasonable total (normalized)
3. VERIFY each criterion is measurable (not vague)
Rubric validated
1. WRITE rubric to x-ipe-docs/memory/.working/rubric/{app_name}-re-rubric.md
2. RETURN operation_output with success, rubric_metrics, acceptance_criteria
Rubric written and returned
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: string, priority: float}[]
- Writes To: x-ipe-docs/memory/.working/plan/
- Constraints: suggested_extractor can be an
x-ipe-tool-rev-eng-* sub-skill name OR extractor-web/extractor-memory; prioritize by rubric weight; return empty array if no gaps
When: Orchestrator needs to know what knowledge is still missing and which extractor can fill it.
<operation name="request_knowledge">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework, current_state, rubric
2. IDENTIFY the Section → Sub-Skill Map from the framework
3. UNDERSTAND which sections are filled, empty, or partial
</action>
<output>Gap landscape understood</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework contains 8 RE sections
2. VALIDATE current_state has at least one of filled/empty/partial arrays
3. VALIDATE rubric contains metrics for each section
</action>
<constraints>
- BLOCKING: Missing framework or rubric → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Inputs validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. WALK each framework section and compare against current_state:
- If section in filled_sections and meets rubric threshold → skip
- If section in empty_sections → generate full extraction request
- If section in partial_sections → generate targeted extraction request for missing subsections
2. For each gap, DETERMINE suggested_extractor:
- Primary: the mapped x-ipe-tool-rev-eng-* sub-skill for that section
- Fallback: extractor-memory (for existing knowledge) or extractor-web (for external docs)
3. For each gap, GENERATE specific what_needed description (not vague — e.g., "Extract all REST endpoints with request/response schemas from src/api/")
4. ASSIGN priority from rubric weight (high-weight sections first)
5. SORT knowledge_requests by priority descending
6. IF no gaps remain → return empty knowledge_requests[]
Knowledge requests generated
1. VERIFY each request has target_section, what_needed, suggested_extractor, priority
2. VERIFY suggested_extractor is a valid skill name
3. VERIFY what_needed is specific (≥10 words, references code paths or section IDs)
Requests validated
1. WRITE knowledge_requests to x-ipe-docs/memory/.working/plan/{app_name}-re-plan.md
2. RETURN operation_output with success, knowledge_requests
Plan written and returned
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 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 a structured draft.
<operation name="fill_structure">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input: framework (8 sections), gathered_knowledge[], rubric
2. INDEX gathered_knowledge by section_id for efficient lookup
3. UNDERSTAND framework section structure and expected content per section
</action>
<output>Inputs indexed and understood</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE framework contains 8 RE sections
2. VALIDATE gathered_knowledge is non-empty array
3. VALIDATE each item has section_id, content fields
4. VALIDATE rubric contains criteria for each section
</action>
<constraints>
- BLOCKING: Missing framework or rubric → return error INPUT_VALIDATION_FAILED
- WARNING: Empty gathered_knowledge → proceed but mark all sections [INCOMPLETE]
</constraints>
<output>Inputs validated</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. For each framework section:
a. FIND matching gathered_knowledge entries by section_id
b. MERGE content into the section stub, preserving subsection structure
c. EVALUATE against rubric criteria for that section
d. IF content insufficient → mark with [INCOMPLETE: {reason}]
e. IF content meets rubric → mark section as complete
2. COMPOSE completed_draft by assembling all 8 sections in order
3. ADD metadata header (app_name, generation date, completeness summary)
4. ADD source attribution per section (from gathered_knowledge.source)
Draft assembled with completeness markers
1. VERIFY completed_draft contains all 8 sections
2. VERIFY each section either has content or [INCOMPLETE: reason] marker
3. VERIFY source attribution is present for filled sections
4. COUNT completeness ratio (filled / total sections)
Draft validated
1. WRITE completed_draft to x-ipe-docs/memory/.working/draft/{app_name}-re-draft.md
2. RETURN operation_output with success, completed_draft, completeness_ratio
Draft written and returned
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_ratio: "float"
writes_to: "x-ipe-docs/memory/.working/{sub-path}/"
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 memory writes</name>
<verification>No files written outside x-ipe-docs/memory/.working/</verification>
Sub-skill mapping integrity
provide_framework maps all 8 sections to correct rev-eng sub-skills
Error Handling
| Error | Cause | Resolution |
|---|
INVALID_OPERATION | Operation name not one of the 4 defined | Return error listing valid operations |
INPUT_VALIDATION_FAILED | Required input missing or wrong type | Return error with specific field and expected type |
TEMPLATE_NOT_FOUND | Mixin template file missing | Log warning, proceed with base playbook only |
MIXIN_UNSUPPORTED | Language or repo_type not in supported set | Log warning, skip mixin, use base playbook |
FRAMEWORK_INCOMPLETE | Framework missing expected sections | Return error with list of missing sections |
WRITE_FAILED | Cannot write to .working/ path | Return error; orchestrator decides retry or alternate path |
QUALITY_THRESHOLD_NOT_MET | Draft below rubric quality bar | Return partial results with completeness_ratio; orchestrator decides |
Patterns & Anti-Patterns
| Pattern | When | Key Actions |
|---|
| Incremental fill | Large codebase | Fill sections iteratively via rev-eng sub-skills |
| Mixin composition | Polyglot repo | Stack language + repo-type mixins in provide_framework |
| Sub-skill delegation | Specialized analysis | Map each section to its x-ipe-tool-rev-eng-* sub-skill |
| 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 |
| Generic extraction | Misses domain detail | Use domain-specific rev-eng sub-skills, not generic extractors |
Examples
See references/examples.md for worked examples of each operation.
