Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(generation): one instruction, one 'Questions this page answers' heading (#1073)

Raghav Chamadiya08a94151bc5c
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index 6470437e5..362cea72b 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -33,7 +33,7 @@ from ..models import (
compute_source_hash,
)
from ..styles import ONBOARDING_PAGE_TYPE, resolve_style
-from .helpers import _extract_summary, _now_iso
+from .helpers import _extract_summary, _now_iso, collapse_empty_duplicate_headings
from .pertype import PerTypeGenerationMixin
from .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
from .structural import (
@@ -412,12 +412,15 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
) -> GeneratedPage:
"""Wrap a GeneratedResponse in a GeneratedPage."""
now = _now_iso()
+ # One pass over every model-written page: a heading the model emitted
+ # twice with an empty section between the copies is one heading.
+ content = collapse_empty_duplicate_headings(response.content)
page = GeneratedPage(
page_id=compute_page_id(page_type, target_path),
page_type=page_type,
title=title,
- content=response.content,
- summary=_extract_summary(response.content),
+ content=content,
+ summary=_extract_summary(content),
source_hash=source_hash,
model_name=self._provider.model_name,
provider_name=self._provider.provider_name,
diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.py
index 83da30f63..915a8c7f5 100644
--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py
+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py
@@ -8,6 +8,7 @@ docs and call sites reference them.
from __future__ import annotations
+import re
from collections import defaultdict
from datetime import UTC, datetime
from pathlib import Path
@@ -91,6 +92,31 @@ def overview_summary(content: str) -> str:
return content[:400]
+_EMPTY_DUPLICATE_HEADING = re.compile(
+ r"^(?P<hashes>\#{2,6})[ \t]*(?P<text>\S.*?)[ \t]*\r?\n" # a heading …
+ r"(?:[ \t]*\r?\n)*" # … whose section is empty …
+ r"(?=(?P=hashes)[ \t]*(?P=text)[ \t]*(?:\r?\n|$))", # … and repeats verbatim
+ re.MULTILINE,
+)
+
+
+def collapse_empty_duplicate_headings(content: str) -> str:
+ """Drop a heading that is immediately repeated with nothing in between.
+
+ Models emit this when a required section is asked for emphatically: the
+ heading lands once bare and once with the body under it, which renders as an
+ empty section followed by the real one. A prompt change makes it rarer but
+ cannot make it impossible, so the heading is deduplicated here as well,
+ where the outcome does not depend on the model. Only the empty copy goes;
+ two headings with content between them are two real sections.
+ """
+ prior = None
+ while prior != content:
+ prior = content
+ content = _EMPTY_DUPLICATE_HEADING.sub("", content)
+ return content
+
+
def _is_infra_file(parsed: ParsedFile) -> bool:
"""Return True if the file is an infrastructure file."""
lang = parsed.file_info.language
diff --git a/packages/core/src/repowise/core/generation/page_generator/prompts.py b/packages/core/src/repowise/core/generation/page_generator/prompts.py
index 010e3e9c1..6cf114c09 100644
--- a/packages/core/src/repowise/core/generation/page_generator/prompts.py
+++ b/packages/core/src/repowise/core/generation/page_generator/prompts.py
@@ -47,12 +47,12 @@ SYSTEM_PROMPTS: dict[str, str] = {
"time. A page that walks through files one by one has failed even if every "
"sentence is true. Synthesise. "
"\n"
- "REQUIRED SECTION: end the page with a section '## Questions this page "
- "answers' listing 3 to 6 questions a developer or agent would ask that this "
- "page answers, phrased the way they would actually be asked (for example "
- "'How is the dependency graph built?' or 'Where do I add a new X?'). This "
- "section is mandatory. "
- "\n"
+ # The mandatory '## Questions this page answers' section is asked for once,
+ # in module_page.j2, where the rest of the module-page contract lives.
+ # Stating it here as well made the model stutter the heading: it emitted the
+ # heading bare, then again with the questions under it, on 86 of 92 pages
+ # measured across local indexes (gpt-5.4-nano). Pages written before the
+ # instruction was doubled show none of it. One instruction, one heading.
"Ground every claim in the supplied material: do not invent files, symbols, "
"or rationale that are not listed. Draw on the whole file set, not one file."
),
diff --git a/tests/unit/generation/test_duplicate_heading_collapse.py b/tests/unit/generation/test_duplicate_heading_collapse.py
new file mode 100644
index 000000000..79757e35a
--- /dev/null
+++ b/tests/unit/generation/test_duplicate_heading_collapse.py
@@ -0,0 +1,124 @@
+"""The mandatory module-page section is asked for once, and emitted once.
+
+Background: the '## Questions this page answers' requirement used to be stated
+in both the module_page system prompt and module_page.j2. Measured across local
+indexes, 86 of 92 module pages written under the doubled instruction emitted the
+heading twice — once bare, once with the questions under it. Pages written
+before the instruction was doubled show none of it.
+
+Two guards, because a prompt change is probabilistic and a code path is not:
+the instruction lives in one place, and an empty duplicate heading is collapsed
+on the way into the page.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import repowise.core.generation as _generation
+from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.page_generator import SYSTEM_PROMPTS, PageGenerator
+from repowise.core.generation.page_generator.helpers import (
+ collapse_empty_duplicate_headings,
+)
+from repowise.core.providers.llm.base import GeneratedResponse
+from repowise.core.providers.llm.mock import MockProvider
+
+_SECTION = "Questions this page answers"
+_TEMPLATE_DIR = Path(_generation.__file__).parent / "templates"
+
+
+# ---------------------------------------------------------------------------
+# One instruction, one place
+# ---------------------------------------------------------------------------
+
+
+def test_module_page_system_prompt_does_not_repeat_the_required_section():
+ """The contract lives in module_page.j2 with the rest of the requirements."""
+ assert _SECTION not in SYSTEM_PROMPTS["module_page"]
+
+
+def test_module_page_template_still_asks_for_the_required_section():
+ """Deleting the duplicate must not delete the requirement."""
+ template = (_TEMPLATE_DIR / "module_page.j2").read_text(encoding="utf-8")
+ assert template.count(_SECTION) == 1
+
+
+# ---------------------------------------------------------------------------
+# collapse_empty_duplicate_headings
+# ---------------------------------------------------------------------------
+
+
+def test_collapses_the_observed_failure():
+ """The exact shape seen in production: bare heading, then the real one."""
+ content = (
+ "Some prose about the subsystem.\n\n"
+ f"## {_SECTION}\n\n"
+ f"## {_SECTION}\n"
+ "1. What does this do?\n"
+ "2. Where do I add a new one?\n"
+ )
+ out = collapse_empty_duplicate_headings(content)
+ assert out.count(f"## {_SECTION}") == 1
+ assert "1. What does this do?" in out
+ assert out.startswith("Some prose about the subsystem.")
+
+
+def test_collapses_three_copies():
+ content = f"## {_SECTION}\n\n## {_SECTION}\n\n## {_SECTION}\n1. Why?\n"
+ out = collapse_empty_duplicate_headings(content)
+ assert out.count(f"## {_SECTION}") == 1
+ assert "1. Why?" in out
+
+
+def test_collapses_crlf_line_endings():
+ content = f"## {_SECTION}\r\n\r\n## {_SECTION}\r\n1. Why?\r\n"
+ assert collapse_empty_duplicate_headings(content).count(f"## {_SECTION}") == 1
+
+
+def test_keeps_two_headings_that_both_have_content():
+ """Two real sections with the same name are the model's call, not a stutter."""
+ content = "## Notes\nFirst point.\n\n## Notes\nSecond point.\n"
+ out = collapse_empty_duplicate_headings(content)
+ assert out.count("## Notes") == 2
+ assert "First point." in out
+
+
+def test_keeps_an_empty_section_followed_by_a_different_heading():
+ content = "## Empty\n\n## Different\nBody.\n"
+ assert collapse_empty_duplicate_headings(content) == content
+
+
+def test_leaves_a_clean_page_untouched():
+ content = f"## Overview\nProse.\n\n## {_SECTION}\n1. Why?\n"
+ assert collapse_empty_duplicate_headings(content) == content
+
+
+def test_does_not_touch_repeated_headings_at_different_levels():
+ """``## X`` then ``### X`` is a section and its subsection, not a stutter."""
+ content = "## Design\n\n### Design\nBody.\n"
+ assert collapse_empty_duplicate_headings(content) == content
+
+
+# ---------------------------------------------------------------------------
+# The guard runs on every model-written page
+# ---------------------------------------------------------------------------
+
+
+def test_built_page_collapses_the_duplicate(sample_config):
+ """Whatever the model returns, the stored page has one heading."""
+ duplicated = f"Prose.\n\n## {_SECTION}\n\n## {_SECTION}\n1. Why?\n"
+ provider = MockProvider()
+ gen = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ page = gen._build_generated_page(
+ "module_page",
+ "packages/core",
+ "Core",
+ GeneratedResponse(duplicated, 10, 5),
+ "source-hash",
+ 1,
+ )
+
+ assert page.content.count(f"## {_SECTION}") == 1
+ assert _SECTION not in page.summary or page.summary.count(_SECTION) == 1