UC-06: Feature Planning

When a feature needs a rigorous, tests-first plan grounded in the real codebase before any code is written. Produces an immutable, tests-first sealed plan: a Fit Pack of reusable symbols, the exact files to modify (each cited to a symbol and line range in the code graph), adjudicated duplicate risks, and acceptance criteria each paired with an enforcing test. It plans; it does not write production code.

What Makes It Different

  • Test first. It authors the test diff before the production plan and pairs every acceptance criterion with the test that enforces it.
  • Graph-cited placement. Each planned edit is pinned by symbol overview, call-chain, and analyze_code to a specific class and line range, and can prove a name or field does not already exist.
  • Duplicate-risk adjudication. Fit-Pack duplicate risks are explicitly resolved: reuse, extend, or parallel-implement.
  • Sealed & bound. The plan is immutable and tied to the build; hand-editing it breaks the evidence chain.

Prompt

Prompt
Run RubberDuck UC-06: Feature Planning.


[EDIT INPUTS ONLY]
target = <owner/repo or local path>
branch = auto
commit = latest
feature = <feature goal>
[/EDIT INPUTS ONLY]


Plan only; no repo edits. Required artifact: `FEATURE_PLAN.md`.
Use prod RD current-ref gates: `get_started`, completed `detailed_repo_analysis(..., semantic_mode="full")`, Phase 2 ready, `load_code(max_files=4000)`, source/search/graph evidence.
Stop if ref proof or RD hard gates fail, or if the feature would require unsupported mutation during planning.
Constrain scope explicitly: name what is in scope, out of scope, and what must remain unchanged for compatibility.
Plan around relevant entrypoints, handlers, policy checks, serializers/parsers, external surfaces, residual risks, and tests.
Write `FEATURE_PLAN.md`: scenario, fit analysis, tests-first plan, integration points, security acceptance, implementation sequence, export/PR blockers, method notes.
Security artifact contract: include sections named Security Invariant, Adversarial Probes, Impact/Test Matrix, Evidence-Cleanliness Blockers, Unsupported Clean/Security-Ready Claims.
Acceptance must include adversarial rejection, compatibility preservation, explicit opt-in/policy if retained, and no full-safety claim beyond addressed paths.

Input

Repo, branch/ref, commit, feature request and acceptance criteria.

Output

A sealed feature plan (sealed_plan.json) plus a readable PLAN.md, a test diff, and the Fit Pack, ready for sign-off and a bound build.

What Happens (With RubberDuck MCP)

Tested on Sphinx, planning a new --parallel-write flag for parallel file writing in builders:

1

search_code(pattern="parallel|multiprocess")

Found existing parallel_read_safe and parallel_write_safe patterns in builders

2

query_action(action="symbols_overview", analysis_id="your-analysis-id")

Listed Builder class with 47 methods: identified write_doc() as integration point

3

read_source(function_name="Builder.write")

Read write() method showing sequential doc writing loop

4

search_code(pattern="test.*parallel|test.*build")

Found tests/test_build.py with existing parallel test patterns

5

query_action(action="call_chain", analysis_id="your-analysis-id", method="write_doc")

Traced 12 callers: all builders use write_doc(), good single integration point

6

analyze_code(statement="Design tests...")

Generated test cases following existing conftest.py patterns

Feature plan generated:

  • Tests first: test_parallel_write_basic(), test_parallel_write_disabled(), test_parallel_write_error_handling()
  • Files to modify: builders/__init__.py (add parallel_write flag), application.py (add CLI arg)
  • Pattern to follow: Existing parallel_read_safe implementation
  • What NOT to add: No new dependencies, no custom thread pool (use existing)

Comparison

DimensionWith RubberDuck MCPWithout MCP
Pattern discoverysearch_code found parallel_read_safe pattern instantlyHad to grep and read multiple files to find patterns
Integration pointsymbols_overview + call_chain identified write_doc() as single pointRequired manual code reading to find integration point
Test patternsFound existing test patterns in conftest.py automaticallyHad to search test directory manually
Plan qualitySemantic understanding of code structureSurface-level plan based on file names

Videos

With RubberDuck MCP:

Tested on the Sphinx repo, planning support for preserving binary (0b1010) and octal (0o755) default argument formats in autodoc alongside the existing hex handling, with both RubberDuck MCP servers enabled in Cursor. The agent runs Find Files, Search Code, Symbols Overview, and repeated Read Source and Load Code calls against a loaded graph (analysis_id preserve_defaults_2, complete with node and edge counts) before writing a single line of plan. That evidence pins the mechanism to Python's source-segment lookup helper, called from target/preserve_defaults.py, and the plan states Python 3.8+ needs no code changes at all, while a pre-3.8 fallback would need visit_Constant enhanced with hex()/bin()/oct() reconstruction, a path it flags as probably not worth it since Python 3.7 is EOL.

Without MCP:

Same repo, same feature request, both MCP servers disabled in Cursor's Tools and MCP settings. With no semantic tools to call, the agent falls back to manually reading preserve_defaults.py, test_ext_autodoc_preserve_defaults.py, and Sphinx's unparser module in line numbered chunks, then grepping the tree for hex, binary, and octal literal patterns and for Num and Constant node references. It still arrives at the same fix, crediting the source-segment lookup helper inside visit_Constant() at line 163 of the unparser module and update_defvalue() at preserve_defaults.py line 52, and proposes its own with_binary and with_octal test functions. But every citation comes from files it opened and grepped by hand, not from a queried call graph.