PR Custody

docs: Mercury action generation redesign design doc

@zen-agentchecks n/achecks…zen/mercury-action-generation-redesign → next1 files · +708 −0updated 3mo ago

▸Description· 1 comment

Why

The current action builder and fixer agents in Integrator spend excessive tokens generating and fixing Mercury action code. The builder uses ~50K-200K+ input tokens per action (reading full sibling files as context), and the fixer is invoked on ~40-60% of built actions with runs lasting up to 3 hours. We need a strategy to reduce costs and improve reliability.

What

Adds a design doc (docs/mercury-action-generation-redesign.md) proposing a three-tier generation architecture:
- Tier 1 (~60% of actions): Agent produces JSON specs instead of Python; deterministic AST-based code generator assembles valid code. Zero syntax errors, zero fixer runs.
- Tier 2 (~30%): Template + agent-filled slots. Agent only writes the execute() body; boilerplate is handled by templates.
- Tier 3 (~10%): Full code generation (current approach) with an AST validation + auto-fix pipeline that catches structural issues before runtime.
Two cross-cutting improvements:
- AST skeleton extractor: Reduces context from full action files (~20K tokens each) to compact structural summaries (~300 tokens), a 99% reduction.
- AST validation + auto-fix pipeline: Catches missing imports, error handling, _validate_response usage via pure AST analysis and auto-fixes ~60-70% of common agent mistakes.
5-phase implementation roadmap with effort estimates.
Expected outcome: 60-75% reduction in total token spend across the action generation pipeline.

How to Test

This is a design doc (no code changes). Review the document at docs/mercury-action-generation-redesign.md.

Pre-Review Checklist

I have self-reviewed this PR

Notes

Phases 1 (validation pipeline) and 2 (skeleton extractor) are the highest-ROI starting points — they improve the existing pipeline without changing the generation paradigm.
The doc references existing AST infrastructure in Mercury (28 files) that the new system should build on.

@zen-agent3mo ago

Post-PR Status

Codex Review: Passed (iteration 1) — no actionable issues found. Docs-only change, no code paths affected.

CI Status: All 5 checks green

Unit Tests - Integrator: success
Lint - Integrator: success
Integration Tests: success
Secret Scanning: success
Check File Size: success

Build Checks: make fmt + make chk both passed locally.

Testing: N/A — docs-only PR, no code changes to test.

PR Comments: None to address.

Blockers: None.

loading diff…