BA

backfill-feature

Reverse-engineers documentation and characterization tests for undocumented features to ensure safe refactoring.

Install

mkdir -p .claude/skills/backfill-feature && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/11115" && unzip -o skill.zip -d .claude/skills/backfill-feature && rm skill.zip

Installs to .claude/skills/backfill-feature

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Use when the user says "/backfill-feature", "backfill the ADR", "this feature has no ADR", "I need to document what's already there before I change it", or wants to capture an existing feature's architectural rationale and behaviour *before* modifying it. Reads the relevant code, drafts a reverse-engineered ADR (what is, why it probably looks like this) + Gherkin spec (current behaviour) + characterization tests that lock the current behaviour green. Hands off to /plan-change so the actual change can be layered on top of a documented, tested baseline.
557 chars✓ has a “when” triggerlonger than Claude Code's old 250-char listing cap (fine on current versions)
Advanced

Key capabilities

  • →Reverse-engineer ADRs from existing code
  • →Generate Gherkin specifications for current behavior
  • →Create characterization tests to lock behavior
  • →Identify load-bearing dependencies and invariants
  • →Prepare a documented baseline for future changes

How it works

The agent analyzes existing code to document its current behavior and rationale, then writes tests to lock that behavior before any modifications occur.

Inputs & outputs

You give it
Target feature or code module
You get back
A set of ADR, Gherkin specs, and characterization tests

When to use backfill-feature

  • →Document an undocumented feature before refactoring
  • →Capture architectural rationale for legacy code
  • →Establish a test baseline for a module that lacks specs

About this skill

Backfill a feature

Build the smallest trustworthy baseline needed for the intended change. Backfill evidence and rationale; do not invent historical certainty or document the whole subsystem.

Bound the investigation

Start with the proposed change and identify which existing behavior, interfaces, data, and decisions it could disturb. Read the relevant implementation, tests, history, issues, and repository standards. Trace enough callers and consumers to expose compatibility boundaries.

Separate:

  • facts demonstrated by code, tests, or observed behavior;
  • rationale supported by records or history;
  • plausible inference that still needs validation;
  • behavior that appears accidental but is currently depended upon.

Keep the baseline focused on decisions the upcoming work must respect.

Create evidence where it helps

Add characterization tests when current behavior is important, observable, and insufficiently protected. Use a focused experiment or prototype to answer uncertain runtime or integration questions. Preserve the existing behavior during this phase unless the user has also authorized the actual change.

Choose the artifact that fits the repository and risk: notes in the work record may be enough; a feature description, decision record, behavioral spec, diagram, or tests may be warranted. Follow local formats when present. Cross-link durable artifacts where that improves discovery.

Record the baseline

Maintain a compact record containing:

  • the objective and non-goals of the upcoming change;
  • current behavior and evidence;
  • known and inferred decisions, clearly labeled;
  • applicable standards and references;
  • compatibility boundaries and acceptance evidence;
  • open questions, tasks, and observations.

Use the repository's preferred work record when available, otherwise keep an equivalent local artifact or working-state summary. Replace claims disproved by later evidence.

Handle discoveries

Resolve scope-relevant blockers and required standards before declaring the baseline ready. Record unrelated quality or UX issues; briefly flag meaningful nonblocking ones and continue. Revisit them at a relevant boundary or final review, and give each an explicit disposition without assuming every observation must be fixed.

Hand off

The baseline is sufficient when planning or implementation can distinguish intended compatibility from incidental structure. Summarize what is known, what is inferred, what is protected by tests, and what remains open. Continue with plan-change when design work remains, or with implementation when the intended delta and acceptance are already clear. Companion skills are optional; perform the next work directly if needed.

When not to use it

  • →Trivial changes like copy edits
  • →Code that already has ADR, spec, and tests
  • →Brand-new features

Limitations

  • →Cannot fix bugs during the backfill process
  • →Requires user confirmation of the feature behavior before drafting
  • →Tests may remain unverified if the runner is not executed

How it compares

This approach establishes a verified, documented baseline before refactoring, rather than modifying undocumented code directly.

Compared to similar skills

backfill-feature side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
backfill-feature (this skill)05moReviewAdvanced
antfu66moReviewIntermediate
code-review-checklist34moNo flagsBeginner
qlty-check510moReviewBeginner

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry