function-distiller

name

function-distiller

description

Research an external or internal software repo, distill one narrow module/function into a minimal self-contained implementation, and verify equivalence without copying code. Use for dependency removal, framework research, API-compatible local reimplementation, DeepWiki/GitHub-based source study, or clean-room behavior specs of pure or near-pure functions. For bounded framework capabilities (state machine + protocol + adapters + async), use capability-distiller instead.

Function Distiller (Mode A / B)

Install destination: copy this folder to .agents/skills/function-distiller/ in your target repo (Codex / AGENTS.md-compatible agents). Sibling skill: capability-distiller for Mode C (bounded framework capabilities).

Purpose

Convert a narrow software capability into a local, minimal, tested implementation.

The unit of reuse is not a repository, package, class hierarchy, or file. The unit of reuse is the function contract:

Function = contract + mechanism + invariants + tests
Library  = function + generality + compatibility + history + ecosystem + packaging

Activation criteria

Use this skill when the task includes any of these phrases or goals:

• "rip out" or "extract" a specific library feature
• remove a heavy dependency
• research how a framework implements a function
• implement a self-contained version of a module
• preserve an API while avoiding the original dependency
• DeepWiki MCP + GitHub CLI repo study
• clean-room implementation from public behavior

Do not use this skill for broad framework rewrites, full clones, security-critical primitives, cryptography, payment, authentication, regulated workflows, or projects where the source license/ToS forbids the required analysis.

Required inputs

If missing, infer conservatively from the repository and state assumptions:

• target repository or local path
• target function/module/capability
• local use case
• required API compatibility
• non-goals
• constraints on dependencies, performance, runtime, and license

Canonical resources (single source of truth)

These paths are repo-root-relative. The kit ships ONE copy of each. The sibling assets/POINTER.md simply redirects here to avoid drift.

• Templates → templates/ (use scripts/make_distillation_workspace.py to copy them into .distillations/<target>/)
• References → references/
• Prompts → prompts/00_target_brief.md ... prompts/10_subagent_clean_room_implementer.md
• Helper scripts → scripts/
• Worked example → examples/markdown-table-parser/

Phase 0 — Triage

Before researching deeply or writing code, assess whether the task should proceed.

Return exactly one decision: GO, SPIKE, or NO-GO. Use prompts/01_go_no_go.md.

Assess:

1. Is the function boundary narrow?
2. Can behavior be tested against an oracle?
3. Is the source open-source, public API, or closed-source?
4. Is the license/ToS compatible with the intended use?
5. Is estimated implementation size likely below 500 lines?
6. Are hidden invariants likely manageable?
7. Is this security/cryptography/auth/payment/medical/legal critical?
8. Would deleting the dependency actually improve the project?

If NO-GO, stop after explaining alternatives.

Phase 1 — Research

Use available tools in this order:

1. DeepWiki MCP if available.
2. GitHub CLI or local clone for source verification.
3. rg, tests, examples, docs, and package metadata.
4. Existing project code to identify actual usage.

See references/deepwiki-github-cli-playbook.md. Write evidence into .distillations/<target>/research-notes.md (template: templates/research-notes-template.md). Every claim must cite at least one source/test/example/observation.

Phase 2 — Slice report

Create .distillations/<target>/slice-report.md from templates/slice-report-template.md. Required fields: target summary, public API, call graph, core logic, core primitives, accidental complexity, hidden invariants, external dependencies, minimal implementation plan, verification plan, risks, GO/SPIKE/NO-GO.

Optional: .distillations/<target>/mechanism-map.md (templates/mechanism-map-template.md) when the mechanism is non-trivial.

Do not implement until this is complete.

Phase 3 — Functional spec

Create .distillations/<target>/functional-spec.md from templates/functional-spec-template.md. Required fields: purpose, non-goals, public API contract, inputs/outputs/errors, state and side effects, algorithm in behavior language, invariants, edge cases, test oracle, tolerance/perf, open questions.

Score it against references/spec-quality-rubric.md. Below 8/10 → revise.

The spec must describe behavior, not copied source structure.

Phase 4 — Implement

Implementation rules (also in references/distillation-principles.md and references/bacterial-code-checklist.md):

• Write original code.
• Do not copy source code, comments, structure, or non-required names.
• Keep the implementation self-contained where practical.
• Avoid new dependencies unless clearly necessary.
• Support only the declared use cases and non-goals.
• Prefer explicit functions over framework abstractions.
• Document every retained hidden invariant.
• If the spec is insufficient, update the spec before changing code.

For high-copying-risk targets, use prompts/10_subagent_clean_room_implementer.md to spawn a fresh subagent that only sees the spec.

Recommended files:

src/<local_module>.*
tests/test_<local_module>.*
.distillations/<target>/implementation-plan.md

You may seed test stubs with python3 scripts/spec_to_test_stub.py .distillations/<target>/functional-spec.md.

Phase 5 — Verify

Run before final response:

• Contract tests (public API behavior).
• Differential tests (compare with original library/API when allowed; use scripts/compare_jsonl_outputs.py for tolerant numeric diff).
• Edge-case tests.
• Property/metamorphic tests when practical.
• Benchmarks if speed/memory/dep-size/build-time motivated the work (scripts/benchmark_command.py).

For numerical code, include tolerance, dtype, device, layout, compile/JIT/autocast behavior when relevant.

Phase 6 — Review

Create .distillations/<target>/verification-report.md from templates/verification-report-template.md. Run python3 scripts/lint_distillation.py .distillations/<target> — must exit 0.

Independent reviewer uses prompts/07_review.md and templates/review-gate-template.md.

Closed-source clean-room

For closed-source or contract-restricted targets:

• Allowed: public docs, public APIs, authorized inputs/outputs, error messages, timing/shape/format observations.
• Not allowed: decompilation, bypassing access controls, copying proprietary code, using leaked code, violating NDA/TOS/EULA.
• See docs/CLOSED_SOURCE_GUARDS.md for concrete examples.
• Use prompts/08_closed_source_clean_room.md and templates/clean-room-observation-log-template.md.
• Prefer role separation; prefer subagent isolation (prompts/10_subagent_clean_room_implementer.md).

Iteration after upstream change

Use prompts/09_iterate.md. Re-run the verifier; only update spec/implementation if the new behavior is desired.

Final answer format

Decision: GO / SPIKE / NO-GO
Distilled insight: <one paragraph>
Files changed:
- ...
Verification:
- tests run
- result
Known limitations:
- ...
Maintenance notes:
- ...