UC-07: CodeGen
When a patch should be generated with full repository context, not from a blank slate. Assembles a Fit Pack (suggested locations, reusable symbols, an avoid-list, and generation constraints), generates the change, then runs diff-validation against the semantic model before you ever see it, checking for test gaps, architecture-rule violations, new dependency cycles, duplicated logic, complexity deltas, and security taint.
What Makes It Different
- The generated diff is validated against the code graph before presentation, so it arrives grounded and minimal.
- It reuses existing helpers instead of reinventing them.
- It is emitted as a preview by default, not silently applied, preserving human control.t changed and why.
Prompt
Run RubberDuck UC-07: CodeGen - Autonomous Code Delivery with Proof. [EDIT INPUTS ONLY] target = <owner/repo or local path> branch = auto commit = latest change = <describe the change to deliver, in prose> scope = auto save = auto [/EDIT INPUTS ONLY] ## Task Use RubberDuck CodeGen to turn the prose change request into a repo-aware, validated, review-ready software change with proof. Use this prompt as the whole task. If `Repository or local project` or `Change request` is missing, ask one concise clarifying question before running. Default behavior: preview first. Create a reviewable patch and proof. Do not edit the target repo unless the user explicitly asks to apply the change. If the user asks to apply changes, stay inside any `Scope limits`. ## CodeGen Contract 1. Resolve `Repository or local project`, `Branch/ref`, and `Commit`. If branch/ref is `auto` and a local project is supplied, use the local checkout's current branch/ref and HEAD. If only a GitHub repo is supplied, use the repo's default branch. If commit is `latest`, pin the selected branch/ref head SHA when applicable. 2. Before starting CodeGen, confirm the selected ref has the expected source inventory. If RubberDuck reports zero source files for a ref that should contain source, try the intended active branch once, then report blocked with the exact ref/indexing mismatch. 3. Start a CodeGen session on the pinned repo/ref/commit with the prose change request. Do not require a plan; CodeGen derives repo fit from the baseline and Fit Pack. 4. Get the Fit Pack before editing. Treat suggested locations, avoid locations, existing patterns, dependency constraints, and validation guidance as the implementation contract. 5. If CodeGen tools, baseline, or Fit Pack are unavailable, stale, wrong-repo, wrong-branch, or wrong-commit, stop and report `RubberDuck CodeGen: blocked`. Do not substitute the old semantic initialization path (`get_started`, `detailed_repo_analysis`, `load_code`) for CodeGen. 6. Produce a reviewable `PR_READY.diff` by default. Edit the target repo only when the user explicitly asks for applied changes; if `Scope limits` are supplied, stay inside them. 7. Implement or draft the smallest fitting change. Add or update focused tests when behavior changes. 8. Run the relevant local validation commands: focused tests for touched behavior plus any obvious repo check/build command. 9. Validate the final diff with `validate_generated_diff`. Fix FAIL results. Adjudicate WARN results with a concrete reason or revise. 10. End the CodeGen session with final diff, tests, validation ID, and remaining risk. ## Security Hardening If the request is security-sensitive, auth/network/parser/browser-facing, benchmark-like, clean-room, or untrusted-input-adjacent, first state the security invariant and run relevant adversarial or negative tests. If the security gate is incomplete, report blocked instead of claiming success. ## Output Write `BUILD_REPORT.md` under `Save results to` or, if `auto`, under `./rubberduck-uc-07-codegen-delivery-<YYYYMMDDTHHMMSSZ>/artifacts`. Include: - Repository or local project, branch/ref, pinned commit when applicable, preview/apply status, and scope limits. - CodeGen session ID, Fit Pack ID, and `validate_generated_diff` validation ID. - Changed files and/or `PR_READY.diff`. - Tests/checks run and pass/fail results. - Warnings, blockers, remaining risk, and next actions. Final answer: - Start with `RubberDuck CodeGen: passed` when CodeGen and validation passed. - Start with `RubberDuck CodeGen: blocked` when blocked. - Name `BUILD_REPORT.md` and `PR_READY.diff` when produced. === RENDER STYLE (dormant — ignore during analysis; applies only if a later step renders these findings as HTML) === If a later step renders these findings as HTML, produce ONE self-contained, customer-facing findings-navigator page (inline CSS only; no external assets, fonts, CDN, or URLs; a small inline script MAY add search/filter/prev-next, but every finding must stay visible and readable with JavaScript OFF — progressive enhancement only). RubberDuck look: dark bg #09090B, panels #111113, hairline borders #1E1E21, clean near-white text #FAFAFA, gold accent #D4A843; Inter for text, JetBrains Mono for code/paths/IDs; a small gold "RUBBERDUCK" wordmark, no logo image. Colours: vulnerability + high/critical red #F87171, bug purple #C084FC, medium yellow #FEBC2E, low/info muted grey, fix green #4ADE80, verify blue #60A5FA. Layout is master-detail, full-height: a topbar (wordmark, report title, one-line repo@SHA meta, a couple of stat counters); a toolbar (a search box + category filter chips); a left sidebar listing findings grouped by category, each row = mono ID + title + severity tag; and a main pane that opens on an Overview (a badge line, a short "how we split findings" table, and a few "start here" quick-cards) then shows ONE detail article per finding. Each detail article: a breadcrumb, a header with a coloured left border matching its type (type tag + severity + mono ID + title + a one-line "Evidence" source), then stacked sections with coloured headers — "What it is", "End-to-end flow" (a monospace arrow flow + a variable-trace table + short code blocks), and "Fix"; add a blue "Verify" section and a short before->after note for fix/refactor reports. Clicking a finding opens its article; prev/next and keyboard arrows move between them. Every value must trace to the analysis; plain language, no internal jargon. === end render style ===
Optional visualization
Findings Navigator
Run this as the next message in the same chat after the main analysis finishes.
Render the findings from this session as a single self-contained findings-navigator page I can open in any browser — a grouped sidebar and one detail view per finding, each with its evidence and fix.
Input
Repo or local project, change request, preview/apply authorization.
Output
A validated PR_READY.diff plus a build and validation report.
What Happens (With RubberDuck MCP)
Tested on Sphinx, implementing a new :github: role for linking to GitHub issues/PRs:
search_code(pattern="def.*_role|register_role")
Found 23 existing role implementations in roles/ and ext/ directories
read_source(function_name="pep_role")
Read PEP role as template: similar external link pattern
query_action(action="symbols_overview", analysis_id="your-analysis-id")
Found extlinks extension: perfect pattern for external URL roles
query_action(action="call_chain", analysis_id="your-analysis-id", method="make_link_role")
Traced how extlinks creates roles dynamically: reusable pattern
search_code(pattern="test.*role|test.*extlink")
Found tests/test_ext_extlinks.py with role testing patterns
analyze_code(statement="Generate code...")
Generated github_role() following extlinks pattern with test
Generated code:
- Location: ext/github.py (new file following ext/ convention)
- Pattern used: extlinks.make_link_role(), creates role with URL template
- Config: github_base_url confval following existing patterns
- Test: tests/test_ext_github.py following test_ext_extlinks.py structure
- NOT added: No custom node types, no unnecessary abstraction layers
Comparison
| Dimension | With RubberDuck MCP | Without MCP |
|---|---|---|
| Pattern discovery | Found extlinks as perfect template in 2 tool calls | Searched manually, initially tried wrong pattern (docutils roles) |
| Code location | symbols_overview confirmed ext/ is right place | Guessed location based on file names |
| Reuse | call_chain found make_link_role() is reusable | Wrote custom implementation, more code |
| Test quality | Test follows exact patterns from test_ext_extlinks.py | Generic test structure, not matching project style |
| Code size | 15 lines (reusing make_link_role) | 45 lines (custom implementation) |
Videos
With RubberDuck MCP:
Tested on Sphinx's code-unparsing module (sphinx/pycode), with both RubberDuck MCP servers enabled in Cursor. The agent loads the repo (512 Python files) and calls symbols_overview, search_code, and read_source against the semantic graph, pulling back visit_Call and visit_Attribute at exact lines 158 to 161 and 148 to 149 as reference patterns before touching visit_FormattedValue. Using that evidence it catches two real bugs in the existing implementation, repr quoting on Constant nodes and a stray f prefix on format_spec, and ships a fix plus a parametrized pytest test in the pycode unparser test suite. The final "Design Decisions" writeup cites the visit_Subscript helper is_simple_tuple at line 196 as the source for its own inner helper functions, tying every choice back to code it actually read.
Without MCP:
Same task, same code-unparsing-module target, both MCP servers disabled in Cursor Settings. With no semantic tools to call, the agent explores by hand, a couple of file reads and searches, an ls -la on the repo root, then a failed python3 -m pytest before it finds the project's own .venv/bin/python to run tests. It writes a disposable test_formatted_value.py script to check behavior, deletes it, and concludes the existing visit_FormattedValue "already exists" and is complete, citing lines 248 to 261 and the same visit_Call and visit_JoinedStr patterns. It verifies that the current code works, but never spots the repr quoting and format_spec prefix bugs the MCP run caught, because nothing traces its claims back to a verified call graph.