Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
fix: stop the synthesizer trading coverage and mechanism depth for cleaner prose (#56)
Jordan Gibbsca052fadb402
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fd9d8ba..b680069 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,15 @@## [Unreleased]+### Coverage before elegance: the synthesizer stops trading substance for prose++A rerun of a comparison query scored below its own older baseline on comprehensiveness and insight, and reading both reports side by side showed why: same word count, spent differently. The humanization work (primers, calm citations, one committed thesis) had quietly taught the synthesizer to dissolve a systematic ten-axis comparison into an elegant narrative and to compress a fully developed quantitative mechanism down to a one-line mention. Cleaner to read, and worse on exactly the axes a "compare X, Y, Z" prompt is graded on. The prompts were conflating two different edits: cutting prose, which is right, and cutting substance, which is not.++- **The synthesizer now treats coverage and mechanism depth as content, not optional structure.** On a compare or survey task, every decision-relevant dimension the corpus names gets explicit coverage, and a mechanism the sources develop (a named decomposition, a formula with its terms, a causal chain with its numbers) gets developed in the report rather than gestured at. The rule it now follows: elegance is spent on the words between points, never on the number of points.+- **"Selectivity" is now defined precisely.** The anti-sprawl guidance used to read as license to drop points; it now says selectivity means choosing which sources to cite for a point, not which points to make. Dropping a comparison axis or compressing a mechanism is a coverage gap, not economy.+- **The length pass cuts prose, never points.** When trimming to the word ceiling, redundancy and filler go first; a comparison dimension, a developed mechanism, a counterargument, and a load-bearing primary source are off limits. If prose cuts do not get under the ceiling, the report has too many words per point, not too many points.+- **Two adversarial backstops.** The depth critic now flags a developed quantitative mechanism compressed to a bare mention as the highest-insight loss a draft can take. The instruction critic gains a comparison-axis coverage check (register-independent, since a comparison prompt needs its axes covered whatever the register) that names dropped or compressed dimensions.+### Run levers: auto-selected register, domain notes, and inference depthThe pipeline had one hard-coded voice (evaluative-argumentative), so a "teach me X" or "survey the landscape" query got an opinionated verdict report. The Q62 register experiment showed the judge prices register heavily (+2.5 RACE from register alone), so register is now a run-time lever instead of a constant.diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.pyindex 2815f50..b180aca 100644--- a/src/hyperresearch/core/hooks.py+++ b/src/hyperresearch/core/hooks.py@@ -773,6 +773,14 @@ prompt. No block = this prompt's defaults apply unchanged.interim note actually provides- A named mechanism is mentioned but not explained even though theinterim note explains it+ - **A developed quantitative mechanism is compressed to a bare mention.**+ The interim note works a named decomposition (e.g. a factor model with+ its loadings), a formula with its terms, or a specific causal chain with+ its numbers — and the draft names it in one clause and moves on. This is+ the highest-insight loss a draft can take: the mechanism was the whole+ reason the depth budget was spent, and a gesture at it recovers none of+ that value. Flag it `major` and tell the revisor to develop it to the+ depth the interim note supports.- A comparison between sources is summarized but the actualdisagreement is blanded out- A citation is dropped where the interim note specifically supports@@ -1230,6 +1238,23 @@ matters here) before the judgment starts — emit ONE finding:- `recommendation`: name the sections that need a primer and, foreach, the concept the primer should teach+**Check R6: Comparison-axis coverage.**+If the report compares 3+ entities (the same trigger as R4) AND the+prompt-decomposition's coverage matrix or required items name+decision-relevant comparison dimensions that the report omits entirely+or compresses to a passing mention (dissolved into a thesis instead of+worked explicitly), emit ONE finding:+ - `failure_mode`: `"missing-comparison-dimensions"`+ - `severity`: `major`+ - `recommendation`: name the dropped or compressed axes and suggest+ giving each explicit coverage (a table row plus a sentence of why it+ matters). A "compare X, Y, Z" prompt is scored on how many+ decision-relevant dimensions the report actually works.+This check is register-INDEPENDENT — a comparison prompt needs its axes+covered in analyze, survey, and advocate alike — so apply it regardless+of the Run directives register (the register guard below governs only+committed-ranking demands, which is a different thing from axis coverage).+**Cap:** At most **3** readability-structural findings total. Do notlet these crowd out core instruction-following findings. Use`"readability-structural"` as the `atomic_item` prefix for these.@@ -2176,6 +2201,29 @@ permitted to be uneven — pass 2 cleans it up. Goals for pass 1:primer is not filler; it is the on-ramp that makes the density thatfollows legible. Skip it only for the executive summary and forshort connective sections with nothing new to explain.+12. **Coverage and mechanism depth are load-bearing content, spent before+ elegance.** Two failure modes cost more points than any prose flaw, and+ both hide as "tightening":+ - *The comparison surface.* On a compare/survey task, the systematic+ multi-dimensional comparison IS content, not optional structure. Every+ dimension the corpus treats as decision-relevant — read them off+ `comparisons.md` and `source-tensions.json` — gets explicit coverage:+ a table row and a sentence of why it matters. Do NOT dissolve a+ ten-axis comparison into a single elegant thesis that gestures at the+ axes. A "compare X, Y, Z" prompt is scored on how many decision-relevant+ dimensions you actually work, so a narrative that absorbs the comparison+ covers less than a report that lays it out.+ - *Developed mechanisms.* A quantitative mechanism the sources develop —+ a named decomposition (e.g. a factor model with its loadings), a formula+ with its terms, a specific causal chain with its numbers — must be+ DEVELOPED in the report, not compressed to a one-line mention. A+ mechanism named but not unpacked has lost the exact insight that made it+ worth citing; it reads as a gesture, and the insight score reflects that.+ When an interim note works a mechanism in depth, carry that depth+ through — that is what the depth budget was spent on.+ Elegance is spent on the words BETWEEN points, never on the number of+ points. If you must choose, on these tasks coverage and developed depth+ win over a cleaner line.Pass 1 length target: in the response_format range, leaning slightly long(15-20% over target). Pass 2 cuts.@@ -2192,7 +2240,12 @@ point is a forced compression rewrite of your own output. Count your wordsbefore finishing pass 2; if you are over the ceiling, cut until you areunder it. A large corpus is never a reason to exceed the ceiling —selectivity is the skill being graded, and burying the argument under-every available source scores WORSE on insight, not better.+every available source scores WORSE on insight, not better. But be exact+about what selectivity means: it is choosing which SOURCES to cite for a+point, not which POINTS to make. Cutting a comparison dimension or+compressing a developed mechanism to a bare mention is not selectivity —+it is a coverage and insight gap that scores worse, not better. Prune+redundant citations of the same point; never prune the point.When pass 1 is done, write it to `pass1_output_path`.@@ -2238,7 +2291,7 @@ drafts. State the committed position from the synthesis plan.### Length discipline-If pass 1 is over the response_format target, CUT. Specifically:+If pass 1 is over the response_format target, CUT. Cut prose, never points:- Cut the most redundant sentences first (you've already flagged them above)- Cut filler ("It is worth noting", "Importantly", "Of note,", "It bearsmentioning")@@ -2246,6 +2299,12 @@ If pass 1 is over the response_format target, CUT. Specifically:is restating- Drop weak adverbs ("really", "quite", "notably" when not load-bearing)+What you NEVER cut to hit the target: a comparison dimension, a developed+quantitative mechanism, a counterargument, or a load-bearing primary source.+Those are points, not prose. If cutting redundancy and filler does not get+you under the ceiling, the report has too many words per point, not too many+points — tighten more points, do not amputate one.+If pass 1 is under target, EXPAND. Specifically:- Add interpretive beats where you have factual claims withoutconclusionsdiff --git a/tests/fixtures/golden_prompts/agents/depth_critic_agent.md b/tests/fixtures/golden_prompts/agents/depth_critic_agent.mdindex 08661bf..63a20d3 100644--- a/tests/fixtures/golden_prompts/agents/depth_critic_agent.md+++ b/tests/fixtures/golden_prompts/agents/depth_critic_agent.md@@ -66,6 +66,14 @@ prompt. No block = this prompt's defaults apply unchanged.interim note actually provides- A named mechanism is mentioned but not explained even though theinterim note explains it+ - **A developed quantitative mechanism is compressed to a bare mention.**+ The interim note works a named decomposition (e.g. a factor model with+ its loadings), a formula with its terms, or a specific causal chain with+ its numbers — and the draft names it in one clause and moves on. This is+ the highest-insight loss a draft can take: the mechanism was the whole+ reason the depth budget was spent, and a gesture at it recovers none of+ that value. Flag it `major` and tell the revisor to develop it to the+ depth the interim note supports.- A comparison between sources is summarized but the actualdisagreement is blanded out- A citation is dropped where the interim note specifically supportsdiff --git a/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md b/tests/fixtures/golden_prompts/agents/instruction_critic_agent.mdindex 81abac6..769ad69 100644--- a/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md+++ b/tests/fixtures/golden_prompts/agents/instruction_critic_agent.md@@ -256,6 +256,23 @@ matters here) before the judgment starts — emit ONE finding:- `recommendation`: name the sections that need a primer and, foreach, the concept the primer should teach+**Check R6: Comparison-axis coverage.**+If the report compares 3+ entities (the same trigger as R4) AND the+prompt-decomposition's coverage matrix or required items name+decision-relevant comparison dimensions that the report omits entirely+or compresses to a passing mention (dissolved into a thesis instead of+worked explicitly), emit ONE finding:+ - `failure_mode`: `"missing-comparison-dimensions"`+ - `severity`: `major`+ - `recommendation`: name the dropped or compressed axes and suggest+ giving each explicit coverage (a table row plus a sentence of why it+ matters). A "compare X, Y, Z" prompt is scored on how many+ decision-relevant dimensions the report actually works.+This check is register-INDEPENDENT — a comparison prompt needs its axes+covered in analyze, survey, and advocate alike — so apply it regardless+of the Run directives register (the register guard below governs only+committed-ranking demands, which is a different thing from axis coverage).+**Cap:** At most **3** readability-structural findings total. Do notlet these crowd out core instruction-following findings. Use`"readability-structural"` as the `atomic_item` prefix for these.diff --git a/tests/test_core/test_prompt_golden.py b/tests/test_core/test_prompt_golden.pyindex 51ae221..bdd254e 100644--- a/tests/test_core/test_prompt_golden.py+++ b/tests/test_core/test_prompt_golden.py@@ -73,6 +73,16 @@ Deliberate deviations already folded into the goldens (2026-07-19):register-conditional standards. The cite-checker and9-evidence-digest are deliberately untouched (no shim: verificationis register-independent; step 9 spawns nothing).+ - Coverage before elegance (2026-07-22, after the Q52 rerun scored below+ baseline on comprehensiveness and insight by trading the systematic+ comparison surface and a developed factor decomposition for a cleaner+ thesis, at the same word count): the depth critic gained a shallow-spot+ bullet for developed quantitative mechanisms compressed to a bare mention+ (the highest-insight loss), and the instruction critic gained check R6+ (comparison-axis coverage, register-independent). The synthesizer (not+ golden-covered) gained pass-1 item 12 (coverage and mechanism depth are+ load-bearing content), a reframed selectivity paragraph (select sources,+ not points), and a "never cut a point to hit the ceiling" clause."""from __future__ import annotations@@ -363,3 +373,35 @@ def test_cite_check_skill_gets_no_shim(ctx):_read_skill_source("hyperresearch-14-5-cite-check.md"), ctx)assert "shims/" not in rendered+++# ---------------------------------------------------------------------------+# Coverage before elegance: the synthesizer and the depth/instruction critics+# must carry the anti-compression guards so a rerun can't silently regress into+# trading substance for prose (see the 2026-07-22 deviation-log entry).+# ---------------------------------------------------------------------------+++def test_synthesizer_carries_coverage_before_elegance_guards(ctx):+ rendered = render_prompt(hooks.SYNTHESIZER_AGENT, ctx)+ # pass-1 item 12: coverage + mechanism depth are load-bearing content+ assert "load-bearing content" in rendered+ assert "Elegance is spent on the words BETWEEN points" in rendered+ # reframed selectivity: pick sources, not points+ assert "which SOURCES to cite for a" in rendered+ assert "not which POINTS to make" in rendered+ # length discipline: never cut a point to hit the ceiling+ assert "Cut prose, never points" in rendered+++def test_depth_critic_flags_compressed_mechanisms(ctx):+ rendered = render_prompt(hooks.DEPTH_CRITIC_AGENT, ctx)+ assert "compressed to a bare mention" in rendered+ assert "highest-insight loss" in rendered+++def test_instruction_critic_has_comparison_axis_check(ctx):+ rendered = render_prompt(hooks.INSTRUCTION_CRITIC_AGENT, ctx)+ assert "missing-comparison-dimensions" in rendered+ # must be register-independent (applies in analyze/survey/advocate alike)+ assert "register-INDEPENDENT" in rendered