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
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:
search_code(pattern="parallel|multiprocess")
Found existing parallel_read_safe and parallel_write_safe patterns in builders
query_action(action="symbols_overview", analysis_id="your-analysis-id")
Listed Builder class with 47 methods: identified write_doc() as integration point
read_source(function_name="Builder.write")
Read write() method showing sequential doc writing loop
search_code(pattern="test.*parallel|test.*build")
Found tests/test_build.py with existing parallel test patterns
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
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
| Dimension | With RubberDuck MCP | Without MCP |
|---|---|---|
| Pattern discovery | search_code found parallel_read_safe pattern instantly | Had to grep and read multiple files to find patterns |
| Integration point | symbols_overview + call_chain identified write_doc() as single point | Required manual code reading to find integration point |
| Test patterns | Found existing test patterns in conftest.py automatically | Had to search test directory manually |
| Plan quality | Semantic understanding of code structure | Surface-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.