Add Socratic Code Theory Recovery to Brownfield workflow#455
Conversation
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughEine neue Dokumentationsdatei ChangesBrownfield-Workflow-Dokumentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 Minuten Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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. Review rate limit: 0/1 reviews remaining, refill in 48 minutes and 40 seconds.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: 1
🧹 Nitpick comments (1)
docs/brownfield-workflow.adoc (1)
45-50: ⚡ Quick winPrompt-“Codeblöcke” in
[source,language]kapseln (Guideline-Konformität).Die Prompt-Blöcke werden derzeit als Literalblöcke mit
----dargestellt (z.B. Zeilen 45-50 und 113-118). Die Guidelines verlangen für “code blocks” den Einsatz von[source,language]-Delimitern. Das würde Konsistenz/Formatierung (und ggf. Syntax-Handling) verbessern.Bitte jeweils z.B. in einen
[source,txt]-Block umformen (oder eine passende Sprache wählen) statt reinem-----Literalblock.Also applies to: 113-118
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/brownfield-workflow.adoc` around lines 45 - 50, Replace the literal `----` prompt blocks with AsciiDoc source blocks using `[source,txt]` (or another appropriate language) so the two prompt/example blocks are wrapped as `[source,txt]`...`----` → `[source,txt]`...`----`; locate the blocks introduced by the `.Prompt` directive containing the "Analyze the codebase in src/. Identify bounded contexts..." text and the later similar prompt (the other block noted in the review) and convert each to the `[source,txt]` block style, preserving the inner content and surrounding directives.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/brownfield-workflow.adoc`:
- Around line 9-16: Replace all nonstandard AsciiDoc links of the form
link:`#/`...[] with AsciiDoc anchor syntax <<anchor-id,Link Text>> and fix the
specific incorrect reference link:`#/spec-driven-development` to use the correct
anchor/file name (spec-driven-workflow) and appropriate link text; update every
occurrence mentioned (e.g., the spec-driven link in the header and other
link:`#/`...[] instances). Convert all .Prompt blocks into standard source blocks
using [source,language] +---- ... ---- (replace each .Prompt block at the
occurrences around lines 45–50 and 113–118 with [source,Prompt] style or the
correct language tag). Inspect and normalize the table cells that currently use
|{empty}-- and replace them with a standard empty cell representation (e.g.,
just | or |-) so table rendering is consistent. Ensure all replacements preserve
original link texts/anchor IDs and update any anchor IDs if you rename
spec-driven-development → spec-driven-workflow.
---
Nitpick comments:
In `@docs/brownfield-workflow.adoc`:
- Around line 45-50: Replace the literal `----` prompt blocks with AsciiDoc
source blocks using `[source,txt]` (or another appropriate language) so the two
prompt/example blocks are wrapped as `[source,txt]`...`----` →
`[source,txt]`...`----`; locate the blocks introduced by the `.Prompt` directive
containing the "Analyze the codebase in src/. Identify bounded contexts..." text
and the later similar prompt (the other block noted in the review) and convert
each to the `[source,txt]` block style, preserving the inner content and
surrounding directives.
🪄 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: 87f29b02-842b-4a7f-8fc7-e2bf5fda064c
📒 Files selected for processing (1)
docs/brownfield-workflow.adoc
| You have mastered the link:#/spec-driven-development[greenfield workflow]. | ||
| Now you want to apply it to an existing codebase. | ||
|
|
||
| The core principles remain the same: small steps, high autonomy, error correction loops. | ||
| But brownfield projects add a challenge that greenfield projects do not have: *the system already exists*. | ||
| You cannot start with a blank slate. | ||
| You must understand what is there before you change it. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
head -n 250 docs/brownfield-workflow.adoc | cat -nRepository: LLM-Coding/Semantic-Anchors
Length of output: 13732
🏁 Script executed:
# Suche nach Ankerdefinitionen im Dokument
grep -n "\[\[" docs/brownfield-workflow.adoc
# Suche nach alle link:`#/` Referenzen
grep -n "link:`#/`" docs/brownfield-workflow.adoc
# Prüfe auf weitere .adoc Dateien, die Anker definieren könnten
find docs -name "*.adoc" -type f | head -20Repository: LLM-Coding/Semantic-Anchors
Length of output: 1343
🏁 Script executed:
# Prüfe die Struktur einer Anker-Datei
head -50 docs/anchors/arc42.adoc | cat -n
# Suche nach Ankerdefinitionen in den Anker-Dateien
grep -n "\[\[" docs/anchors/arc42.adoc
# Prüfe, ob es ein Build-Skript oder Konfiguration für Links gibt
find . -name "*.yml" -o -name "*.yaml" -o -name "Makefile" -o -name "*.gradle" -o -name "*.xml" | grep -E "(build|config|doc)" | head -10Repository: LLM-Coding/Semantic-Anchors
Length of output: 1612
🏁 Script executed:
# Prüfe die Asciidoc-Linter-Konfiguration
cat .asciidoc-linter.yml
# Suche nach Link-Verarbeitung oder Build-Skripten
grep -r "link:#" . --include="*.js" --include="*.ts" --include="*.py" --include="*.sh" 2>/dev/null | head -20
# Prüfe, ob es eine Dokumentations-Build-Datei gibt
ls -la docs/ | grep -E "(build|publish|render)"
git ls-files | grep -E "^\." | grep -E "(yml|yaml|json)$" | head -20Repository: LLM-Coding/Semantic-Anchors
Length of output: 833
🏁 Script executed:
# Suche nach xref: oder anderen AsciiDoc-Link-Formaten in der Datei
grep -n "xref:" docs/brownfield-workflow.adoc
# Suche nach ähnlichen link:`#/` Patterns in anderen Dateien
grep -r "link:`#/`" docs/*.adoc | head -10
# Prüfe deploy.yml für Hinweise auf Link-Verarbeitung
cat .github/workflows/deploy.yml | head -100Repository: LLM-Coding/Semantic-Anchors
Length of output: 2899
🏁 Script executed:
# Prüfe render-docs.js für Link-Verarbeitung
cat scripts/render-docs.js 2>/dev/null | head -100
# Oder suche nach Scripts im website Verzeichnis
find website -name "*.js" | head -10
# Prüfe Codeblock-Formatierung in anderen adoc Dateien
grep -A 2 "^\." docs/*.adoc | grep -E "(Prompt|source)" | head -20Repository: LLM-Coding/Semantic-Anchors
Length of output: 4183
🏁 Script executed:
# Prüfe spec-driven-workflow.adoc um Muster zu vergleichen
grep -B 2 -A 3 "\[source," docs/spec-driven-workflow.adoc | head -30
# Prüfe ALL .adoc Dateien nach Prompt-Blöcken
grep -n "\.Prompt" docs/*.adoc
# Prüfe, wie andere Dateien Links formatieren
grep -n "<<" docs/*.adoc | head -10Repository: LLM-Coding/Semantic-Anchors
Length of output: 672
🏁 Script executed:
# Prüfe, wie viele Dateien link:`#/` verwenden
grep -r "link:`#/`" docs/ --include="*.adoc" | wc -l
# Prüfe, ob es irgendwelche <<anchor>> Links gibt
grep -r "<<" docs/ --include="*.adoc" | grep -v "<<<" | head -10
# Vergleiche Prompt-Block mit source-Block Beispiel
echo "=== Brownfield Prompt-Block ==="
sed -n '45,50p' docs/brownfield-workflow.adoc
echo ""
echo "=== Spec-Driven source-bash Block ==="
grep -A 5 "\[source,bash\]" docs/spec-driven-workflow.adoc | head -8Repository: LLM-Coding/Semantic-Anchors
Length of output: 1427
🏁 Script executed:
# Prüfe, wie viele .Prompt Blöcke es insgesamt gibt
grep -r "\.Prompt" docs/ --include="*.adoc" | wc -l
# Prüfe, wie andere .adoc Dateien Literalblöcke verwenden
grep -B 1 "^----" docs/spec-driven-workflow.adoc | grep -E "^\." | head -10
# Prüfe die Tabellen-Formatierung genauer
sed -n '195,218p' docs/brownfield-workflow.adocRepository: LLM-Coding/Semantic-Anchors
Length of output: 1500
🏁 Script executed:
# Prüfe, ob spec-driven-development.adoc existiert
find docs -name "*spec-driven-development*" -o -name "*spec-driven-workflow*"
# Prüfe all-anchors.adoc für Include-Struktur
head -30 docs/all-anchors.adocRepository: LLM-Coding/Semantic-Anchors
Length of output: 857
Verwenden Sie AsciiDoc-Standard-Linkformat <<anchor-id,Link Text>> statt link:#/...[]
Die Datei nutzt durchgehend die nicht-standard Syntax link:#/anchor/...[] (z. B. Zeilen 9, 42, 63, 193, 197, 205, 209, 212). Laut Coding Guidelines müssen interne AsciiDoc-Links das Format <<anchor-id,Link Text>> verwenden. Zusätzlich ist die Referenz auf link:#/spec-driven-development`` fehlerhaft – die Datei heißt spec-driven-workflow.adoc, nicht `spec-driven-development.adoc`.
Ersetzen Sie alle link:#/...[] durch korrekte AsciiDoc-Anker und korrigieren Sie den Dateinamen-Fehler.
Ebenso sollten die .Prompt-Blöcke (Zeilen 45–50, 113–118) in [source,language]-Format umgewandelt werden, um den Guidelines zu entsprechen. Die Tabellenzellen |{empty}-- (Zeilen 201, 213, 217) sollten überprüft und standardisiert werden.
Betroffene Zeilen: 9–16, 42–44, 63–64, 45–50, 113–118, 191–218
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/brownfield-workflow.adoc` around lines 9 - 16, Replace all nonstandard
AsciiDoc links of the form link:`#/`...[] with AsciiDoc anchor syntax
<<anchor-id,Link Text>> and fix the specific incorrect reference
link:`#/spec-driven-development` to use the correct anchor/file name
(spec-driven-workflow) and appropriate link text; update every occurrence
mentioned (e.g., the spec-driven link in the header and other link:`#/`...[]
instances). Convert all .Prompt blocks into standard source blocks using
[source,language] +---- ... ---- (replace each .Prompt block at the occurrences
around lines 45–50 and 113–118 with [source,Prompt] style or the correct
language tag). Inspect and normalize the table cells that currently use
|{empty}-- and replace them with a standard empty cell representation (e.g.,
just | or |-) so table rendering is consistent. Ensure all replacements preserve
original link texts/anchor IDs and update any anchor IDs if you rename
spec-driven-development → spec-driven-workflow.
Phase 0.5 now uses two-phase Socratic Code Theory Recovery: - Phase 1: Build Question Tree (5 starting questions, recursive decomposition using arc42/Cockburn/ISO 25010/Nygard as guides) - Team answers Open Questions (typically 10-15, routed by role) - Phase 2: Synthesize documentation with Q-ID traceability Based on controlled experiments (Bausteinsicht, 13k lines Go): - LLM recovers FRs, ACs, building blocks, glossary, security docs - Cannot recover: business context, design rationale, quality goal priorities, aspirational features, performance budgets - 11 targeted questions sufficient to close the gap Added: spec drift detection, reconciliation workflow, Naur 1985 reference, experiment report links, updated prompt cheat sheet. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
raifdmueller
force-pushed
the
feat/socratic-code-theory-recovery
branch
from
d95ed38 to
8ab7663
Compare
2 participants
Summary
Based on controlled experiments with Bausteinsicht (Go, 13k lines):
Also adds: spec drift detection, reconciliation workflow, updated prompt cheat sheet, Naur 1985 and experiment reports in Further Reading.
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Dokumentation