fix(socratic-recovery): make synthesized docs self-contained, cite code not Q-IDs#491
Merged
rdmueller merged 2 commits intoMay 17, 2026
Conversation
Phase 2 synthesized documentation cited only the Q-ID (e.g. [Q3.5]). The file:line code evidence sits in the [ANSWERED] leaf of the Question Tree, so a reader had to open the tree to find where a claim came from. Phase 2 now copies the Evidence line from the [ANSWERED] leaf into the citation alongside the Q-ID — [Q3.5; src/app/Ports.java:12] — so the source location is visible in the documentation itself. Team answers keep the (team answer, Q-ID) form (no code evidence exists); deferred questions stay explicit gaps. Updated the skill (phase-2-synthesize prompt, output-schema, SKILL.md) and the website brownfield-workflow / socratic-recovery-skill docs including the copy-paste Phase 2 cheat-sheet prompt, EN and DE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
WalkthroughDie Pull Request aktualisiert durchgehend die Dokumentation und Prompts zum Socratic-Code-Theory-Recovery-Skill, um die Phase-2-Syntheseregeln präziser zu definieren. Alle änderungen beschreiben die gleiche Traceability-Anforderung: Code-abgeleitete Claims müssen Q-IDs zitieren und verbatim ChangesPhase-2-Traceability-Anforderungen
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md`:
- Around line 146-152: The fenced code block in the markdown lacks a language
specifier (triggering MD040); update the opening fence from ``` to include a
language (e.g., ```text) so the block is explicitly declared (modify the fenced
block that contains "The system uses Hexagonal Architecture ..." to start with
```text).
In `@skill/socratic-code-theory-recovery/references/output-schema.md`:
- Around line 146-152: Die Markdown-Fenced-Code-Block im Abschnitt mit dem Text
"The system uses Hexagonal Architecture..." fehlt eine Sprachangabe, wodurch
MD040 ausgelöst wird; fix: addiere unmittelbar nach den drei Backticks eine
Sprache (z.B. "text") so der Fence lautet ```text, damit der Block korrekt
getaggt ist; suche den dreifachen-Backtick-Fence um den Absatz (die vorhandene
``` ohne Sprache) und ersetze ihn durch ```text (behalte den inneren Inhalt
unverändert).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: b2cd45b7-6202-4ab5-9ec5-a8ce87328a25
📒 Files selected for processing (10)
docs/brownfield-workflow.adocdocs/brownfield-workflow.de.adocdocs/socratic-recovery-skill.adocdocs/socratic-recovery-skill.de.adocplugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-2-synthesize.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.mdskill/socratic-code-theory-recovery/SKILL.mdskill/socratic-code-theory-recovery/prompts/phase-2-synthesize.mdskill/socratic-code-theory-recovery/references/output-schema.md
Comment on lines
146
to
152
| ``` | ||
| The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture]. Sessions | ||
| The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture; | ||
| src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]. Sessions | ||
| expire after 24 hours (team answer, Q3.8.Security.SessionLifetime). | ||
| Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved | ||
| before the next release. | ||
| ``` |
There was a problem hiding this comment.
Fenced Code Block mit Sprache deklarieren
Der Codeblock sollte eine Sprache bekommen, damit MD040 nicht mehr anschlägt.
Vorgeschlagener Fix
-```
+```text
The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture;
src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]. Sessions
expire after 24 hours (team answer, Q3.8.Security.SessionLifetime).
Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved
before the next release.</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 146-146: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md
around lines 146 - 152, The fenced code block in the markdown lacks a language
specifier (triggering MD040); update the opening fence from to include a language (e.g.,text) so the block is explicitly declared (modify the fenced
block that contains "The system uses Hexagonal Architecture ..." to start with
Comment on lines
146
to
152
| ``` | ||
| The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture]. Sessions | ||
| The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture; | ||
| src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]. Sessions | ||
| expire after 24 hours (team answer, Q3.8.Security.SessionLifetime). | ||
| Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved | ||
| before the next release. | ||
| ``` |
There was a problem hiding this comment.
Fenced Code Block mit Sprache deklarieren
Hier fehlt die Sprachangabe am Fence; das triggert MD040.
Vorgeschlagener Fix
-```
+```text
The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture;
src/app/Ports.java, src/adapter/JpaOrderRepository.java:30]. Sessions
expire after 24 hours (team answer, Q3.8.Security.SessionLifetime).
Quality-goal priorities are deferred (Q4.0.deferred) and must be resolved
before the next release.</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 146-146: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @skill/socratic-code-theory-recovery/references/output-schema.md around lines
146 - 152, Die Markdown-Fenced-Code-Block im Abschnitt mit dem Text "The system
uses Hexagonal Architecture..." fehlt eine Sprachangabe, wodurch MD040 ausgelöst
wird; fix: addiere unmittelbar nach den drei Backticks eine Sprache (z.B.
"text") so der Fence lautet text, damit der Block korrekt getaggt ist; suche den dreifachen-Backtick-Fence um den Absatz (die vorhandene ohne Sprache)
und ersetze ihn durch ```text (behalte den inneren Inhalt unverändert).
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
… only The earlier change in this PR put both the Q-ID and the file:line evidence into the final documentation. But the Question Tree is temporary scaffolding — it is renumbered on every Phase 1 re-run — so a Q-ID baked into permanent documentation is a reference into a discarded, renumbered artifact: dead at best, wrong at worst. The synthesized documentation must be self-contained. It cites only durable references: - code-derived claim: the file:line evidence, copied verbatim from the [ANSWERED] leaf — a pointer at the code, the only canonical artifact. - team-supplied fact: marked (team answer), no external reference needed. - deferred question: an explicit gap. The Q-ID stays a Phase 2 build-time device: during synthesis every claim must trace back to a leaf, but the Q-ID is not emitted into the output. This also makes the re-run/diff workflow more robust — claims correlate by code location, not by Q-IDs that change every run. Updates the skill (phase-2-synthesize, output-schema, SKILL.md incl. the workflow diagram) and the website brownfield-workflow / socratic-recovery-skill docs, EN and DE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
raifdmueller
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
In the brownfield Socratic Code-Theory Recovery workflow, Phase 2 synthesized documentation cited the Q-ID (e.g.
[Q3.5]). The Q-ID points into the Question Tree — which is temporary scaffolding, renumbered on every Phase 1 re-run. A Q-ID baked into permanent documentation is a reference into a discarded, renumbered artifact: dead at best, wrong after a re-run.The synthesized documentation is now self-contained — it cites only durable references:
file:lineevidence, copied verbatim from the[ANSWERED]leaf — a pointer at the code, the only canonical, persistent artifact.(team answer), no external reference needed.The Q-ID stays a Phase 2 build-time device: during synthesis every claim must trace back to a leaf, but the Q-ID is not emitted into the output. This also makes the re-run/diff workflow more robust — claims correlate by code location, not by Q-IDs that change every run.
Changes
phase-2-synthesize.md,output-schema.md,SKILL.md(incl. the workflow diagram); plugin mirror auto-synced by the pre-commit hook.brownfield-workflow.adoc/.de.adoc(incl. the copy-paste Phase 2 cheat-sheet prompt),socratic-recovery-skill.adoc/.de.adoc.brownfield-fair-comparisonexperiment report is left as-is — it records a past experiment run.Test plan
npm run buildsucceeds; brownfield + socratic-recovery-skill pages render🤖 Generated with Claude Code