framework-distillation

name	framework-distillation
description	Distill an open-source framework into reusable architecture knowledge. Use when reverse engineering a framework, runtime, workflow engine, orchestration platform, or plugin system to reproduce its architecture, execution model, extension points, and engineering tradeoffs without copying implementation.

Framework Distillation

Overview

Extract architecture, not code.

Use this skill to reverse engineer framework shape, runtime model, extension points, and engineering tradeoffs so another AI or team can reproduce similar architecture in another language or domain.

When to Use

• Reverse engineering framework architecture beyond README and public API
• Studying runtime, lifecycle, state machine, or extension mechanism
• Reproducing similar framework in another language or domain
• Creating AI-readable architecture knowledge packages
• Comparing frameworks by architecture and tradeoffs

Typical targets: agent runtimes, workflow engines, state machine frameworks, plugin systems, orchestration platforms.

When Not to Use

• README summary only
• API tutorial or usage guide
• Line-by-line code walkthrough
• Copy-paste reimplementation
• Feature inventory without tradeoff analysis

If request is close but off-target, redirect scope first.

Required Inputs

Minimum:

• Repository URL or local source path

Recommended:

• Framework name
• Analysis goal
• Target implementation language or domain
• Depth: mini, standard, or deep
• Focus areas

Core Principle

Architecture > Code
Reason > Syntax
Design > API
Tradeoff > Feature
Principles > Implementation

Workflow

1. Check fit; decline or redirect tutorial/API/file-by-file requests.
2. Choose depth from goal. Default standard; use mini for fast first pass, deep for exhaustive reproduction.
3. Scan docs, tests, examples, and repository shape before deep source reading.
4. Extract architecture, runtime, state, data model, extension points, decisions, and tradeoffs.
5. Distill reusable rules and produce output matched to chosen mode and reproduction goal.

Execution Rules

• Lead with architecture, not feature lists.
• Do not drift into tutorial, API inventory, or file-by-file walkthrough.
• Anchor claims to evidence from code, docs, tests, examples, or commit history when available.
• Distinguish observed facts from inference; use Observed, Strong inference, Tentative inference when evidence is thin.
• State incomplete repository access or weak evidence explicitly.
• Tailor analysis to target language, domain, focus areas, and comparison criteria.

Output Modes

• mini — fast first-pass architecture summary
• standard — full architecture extraction for most studies
• deep — exhaustive reverse engineering for framework reproduction

Details in:

• references/output-modes.md
• references/analysis-checklist.md
• references/deliverables.md

Anti-Patterns

Avoid:

• Summarizing README only
• Listing APIs without architecture
• Explaining examples without extracting design
• Describing code without asking why it exists
• Ignoring tradeoffs, failure paths, or extension points
• Copying implementation instead of distilling principles
• Declaring philosophy or rationale as fact when evidence is weak
• Comparing frameworks by feature checklist alone

Supporting References

• references/output-modes.md — output shapes, templates, diagrams
• references/analysis-checklist.md — analysis checklist and quality gate
• references/deliverables.md — deliverable structure and AI simulation prompt
• references/self-test.md — loophole review and fixes applied
• references/simulated-dialogue-tests.md — pressure prompts and scorecard