feat: socratic-code-theory-recovery Claude Code Skill (#473)#478
Conversation
…#473) Package the brownfield Socratic Code-Theory Recovery workflow as an installable Claude Code Skill. Structure: - SKILL.md — when-to-use, contract overview, two-phase workflow diagram - prompts/phase-1-question-tree.md — copy-paste prompt for Phase 1, with post-prompt sanity-check and team-routing instructions - prompts/phase-2-synthesize.md — Phase 2 prompt that consumes the answered tree and produces PRD + Cockburn use cases + arc42 + Nygard ADRs with full Q-ID traceability - references/arc42.md — 12 sections as Q3 decomposition heuristic - references/cockburn-use-cases.md — fields as Q2 sub-questions, persona vs system use cases - references/iso-25010.md — 8 quality characteristics as Q4 sub-questions, with the mechanism-vs-target split - references/nygard-adrs.md — ADR format as Q3.9 sub-tree, what makes a decision architecturally significant, Pugh matrix guidance - references/output-schema.md — strict format for QUESTION_TREE.adoc and OPEN_QUESTIONS.adoc, including Q-ID scheme, [ANSWERED]/[OPEN] block formats, and Phase 2 traceability rules - references/examples.md — worked [ANSWERED] and [OPEN] leaves for each major branch (Q1-Q5) from a hypothetical Order Management context Reference snippets are embedded (per agreed scope) rather than linked, so the skill is usable offline once installed. End-to-end testing on a real codebase is deferred to a follow-up issue. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ 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 (12)
WalkthroughDiese Pull Request führt die neue Claude Code Skill ChangesSocratic Code-Theory Recovery Skill
Sequence Diagram(s)sequenceDiagram
participant User
participant Phase1 as Phase 1
participant Team
participant Phase2 as Phase 2
participant Docs as Output
User->>Phase1: Brownfield code
Phase1->>Phase1: Decompose with guides
Phase1-->>User: QUESTION_TREE.adoc
Phase1-->>User: OPEN_QUESTIONS.adoc
User->>Team: Distribute to roles
Team-->>User: Completed answers
User->>Phase2: Answered tree
Phase2->>Phase2: Synthesize docs
Phase2-->>Docs: PRD, Use Cases, arc42, ADRs
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 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)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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
🧹 Nitpick comments (3)
skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md (1)
5-62: ⚡ Quick winPrompt-Codeblock mit Sprache markieren (MD040)
Der Fence ab Line 5 hat keine Sprachkennung.
textgenügt und hält die Lint-Pipeline sauber.🤖 Prompt for 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. In `@skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md` around lines 5 - 62, The fenced code block in phase-2-synthesize.md starting with ``` (the Phase 2 prompt block) lacks a language tag causing MD040; change the opening fence from ``` to ```text to mark the block language, keeping the block content unchanged so the lint pipeline passes and the file still renders identically.skill/socratic-code-theory-recovery/references/output-schema.md (1)
73-77: ⚡ Quick winFenced Code Blöcke mit Sprache taggen (MD040)
Die Fences ab Line 73, Line 86 und Line 146 haben keine Sprachkennung. Das erzeugt Lint-Warnungen und vermeidbare CI-Noise.
✅ Minimaler Fix
-``` +```text [ANSWERED] Evidence: <file>:<line>[, <file>:<line> ...] <one to three sentences describing the answer>-
+text
[OPEN]
Category: <one of: business-context | design-rationale | quality-goals | stakeholder-context | future-direction>
Ask role: <one or more of: Product Owner | Architect | Developer | Domain Expert | Operations>
<one to three sentences stating precisely what cannot be answered, and why the code is silent on it>-``` +```text The system uses Hexagonal Architecture [Q3.9.HexagonalArchitecture]. 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> Also applies to: 86-91, 146-151 <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.mdaround lines
73 - 77, Die Markdown-Fenced-Code-Blöcke for responses (the blocks containing
"[ANSWERED]", "[OPEN]" and the example paragraph) lack a language tag which
triggers MD040; update each triple-backtick fence used for output examples so
they include the "text" tag (i.e., changetotext) for the blocks showing
"[ANSWERED]", "[OPEN]" and the final illustrative paragraph in output-schema.md;
keep the block contents unchanged and make sure every similar example fence in
that file (the three instances flagged) is updated.</details> </blockquote></details> <details> <summary>skill/socratic-code-theory-recovery/references/examples.md (1)</summary><blockquote> `9-15`: _⚡ Quick win_ **Alle Example-Fences mit Sprachkennung versehen (MD040)** Die ungetaggten Fences verursachen durchgehend markdownlint-Warnungen. Hier reicht ein mechanischer Fix (`text` oder `asciidoc`) für alle Blöcke. Also applies to: 19-26, 32-38, 42-53, 57-70, 76-87, 91-99, 105-111, 115-124, 128-136, 142-149, 153-163, 169-176, 180-188 <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/examples.mdaround lines 9 -
15, Multiple fenced code blocks in examples.md are missing language identifiers
causing markdownlint MD040 warnings; update each triple-backtick fence (e.g.,
the block containing "[ANSWERED] Evidence: src/auth/Role.java:8 ..." and the
other listed example blocks) to include a language tag such as "text" or
"asciidoc" (for example changetotext) so all fences are tagged
consistently and the MD040 warnings are resolved.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with 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.Inline comments:
In@skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md:
- Around line 53-57: Vereinheitliche die Q-ID-Notation auf das eckige
Klammerformat für alle Referenzen: ersetze occurrences of the parenthetical form
"(team answer, Q3.4.2)" und ähnliche mit konsistenten bracket-Notationen like
"[team answer, Q3.4.2]" und passe die Beispielzeilen so alle
Paragraph-Referenzen, Team-supplied facts und deferred questions das gleiche
zitierbare Format "[...]" verwenden; aktualisiere die drei Beispiele in der
Sektion (die Zeilen mit "The system uses Hexagonal Architecture [Q3.5].",
"Sessions expire after 24 hours (team answer, Q3.4.2)." und "Deferred questions
...") so sie einheitlich "[Q...]" bzw. "[team answer, Q...]" nutzen.In
@skill/socratic-code-theory-recovery/references/output-schema.md:
- Around line 75-82: The Evidence syntax is defined inconsistently in the
"Evidence:" section (the Evidence: header and the surrounding bullets), causing
conflicting rules at the spots corresponding to the examples near lines 75 and
81; consolidate into a single canonical, machine-checkable grammar entry (e.g.,
an "Evidence syntax" subsection) and update the existing statements to reference
that single canonical grammar; ensure the canonical grammar explicitly lists
allowed forms (file:line, file::function, file) and the requirement that
Evidence is mandatory, remove the duplicate/contradictory wording in the earlier
"Evidence:" paragraph, and update any sample lines to use the canonical form so
the generator/parser reads only one authoritative definition.
Nitpick comments:
In@skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md:
- Around line 5-62: The fenced code block in phase-2-synthesize.md starting with
opening fence from ``` to ```text to mark the block language, keeping the block content unchanged so the lint pipeline passes and the file still renders identically. In `@skill/socratic-code-theory-recovery/references/examples.md`: - Around line 9-15: Multiple fenced code blocks in examples.md are missing language identifiers causing markdownlint MD040 warnings; update each triple-backtick fence (e.g., the block containing "[ANSWERED] Evidence: src/auth/Role.java:8 ..." and the other listed example blocks) to include a language tag such as "text" or "asciidoc" (for example change ``` to ```text) so all fences are tagged consistently and the MD040 warnings are resolved. In `@skill/socratic-code-theory-recovery/references/output-schema.md`: - Around line 73-77: Die Markdown-Fenced-Code-Blöcke for responses (the blocks containing "[ANSWERED]", "[OPEN]" and the example paragraph) lack a language tag which triggers MD040; update each triple-backtick fence used for output examples so they include the "text" tag (i.e., change ``` to ```text) for the blocks showing "[ANSWERED]", "[OPEN]" and the final illustrative paragraph in output-schema.md; keep the block contents unchanged and make sure every similar example fence in that file (the three instances flagged) is updated.🪄 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:
085a6ce7-9587-42bb-8f4d-eeadc354110e📒 Files selected for processing (9)
skill/socratic-code-theory-recovery/SKILL.mdskill/socratic-code-theory-recovery/prompts/phase-1-question-tree.mdskill/socratic-code-theory-recovery/prompts/phase-2-synthesize.mdskill/socratic-code-theory-recovery/references/arc42.mdskill/socratic-code-theory-recovery/references/cockburn-use-cases.mdskill/socratic-code-theory-recovery/references/examples.mdskill/socratic-code-theory-recovery/references/iso-25010.mdskill/socratic-code-theory-recovery/references/nygard-adrs.mdskill/socratic-code-theory-recovery/references/output-schema.md
| - Every paragraph references the Q-IDs that support it, in square brackets: | ||
| "The system uses Hexagonal Architecture [Q3.5]." | ||
| - Team-supplied facts get an inline marker: "Sessions expire after 24 hours | ||
| (team answer, Q3.4.2)." | ||
| - Deferred questions stay as explicit gaps: "Quality-goal priorities are |
There was a problem hiding this comment.
Q-ID-Notation für Traceability vereinheitlichen
Line 53-54 verlangt Q-IDs in [], aber Line 55-56 nutzt (team answer, Q3.4.2). Für robuste, automatisierbare Traceability sollte ein einziges zitierbares Format gelten (z. B. immer [...], inkl. Team-Answer-Marker).
🤖 Prompt for 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.
In `@skill/socratic-code-theory-recovery/prompts/phase-2-synthesize.md` around
lines 53 - 57, Vereinheitliche die Q-ID-Notation auf das eckige Klammerformat
für alle Referenzen: ersetze occurrences of the parenthetical form "(team
answer, Q3.4.2)" und ähnliche mit konsistenten bracket-Notationen like "[team
answer, Q3.4.2]" und passe die Beispielzeilen so alle Paragraph-Referenzen,
Team-supplied facts und deferred questions das gleiche zitierbare Format "[...]"
verwenden; aktualisiere die drei Beispiele in der Sektion (die Zeilen mit "The
system uses Hexagonal Architecture [Q3.5].", "Sessions expire after 24 hours
(team answer, Q3.4.2)." und "Deferred questions ...") so sie einheitlich
"[Q...]" bzw. "[team answer, Q...]" nutzen.
| Evidence: <file>:<line>[, <file>:<line> ...] | ||
| <one to three sentences describing the answer> | ||
| ``` | ||
|
|
||
| - **Evidence is mandatory.** No exception. A claim without evidence is `[OPEN]`, not `[ANSWERED]`. | ||
| - File paths are relative to the bounded context root. | ||
| - Use `file:line` for a specific line, `file::function` for a function regardless of line drift, `file` for a whole-file claim. | ||
| - Keep the prose factual. The answer is the *what*; the *why* belongs in a separate `[OPEN]` leaf if it isn't in the code. |
There was a problem hiding this comment.
Evidence-Format konsistent und eindeutig machen
Line 75 und Line 81 definieren unterschiedliche zulässige Evidence-Syntax. Für „machine-checkable“ sollte die erlaubte Grammatik an genau einer Stelle vollständig und widerspruchsfrei stehen, sonst laufen Generator und Parser auseinander.
🔧 Vorschlag zur Vereinheitlichung
-[ANSWERED]
-Evidence: <file>:<line>[, <file>:<line> ...]
+[ANSWERED]
+Evidence: <ref>[, <ref> ...]
<one to three sentences describing the answer>-- Use `file:line` for a specific line, `file::function` for a function regardless of line drift, `file` for a whole-file claim.
+- `ref` must be one of: `file:line`, `file::function`, or `file`.🤖 Prompt for 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.
In `@skill/socratic-code-theory-recovery/references/output-schema.md` around lines
75 - 82, The Evidence syntax is defined inconsistently in the "Evidence:"
section (the Evidence: header and the surrounding bullets), causing conflicting
rules at the spots corresponding to the examples near lines 75 and 81;
consolidate into a single canonical, machine-checkable grammar entry (e.g., an
"Evidence syntax" subsection) and update the existing statements to reference
that single canonical grammar; ensure the canonical grammar explicitly lists
allowed forms (file:line, file::function, file) and the requirement that
Evidence is mandatory, remove the duplicate/contradictory wording in the earlier
"Evidence:" paragraph, and update any sample lines to use the canonical form so
the generator/parser reads only one authoritative definition.
) Companion to the skill package itself: - New page docs/socratic-recovery-skill.adoc (EN+DE) with per-tool installation instructions for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and Amazon Kiro. Same per-tool pattern as agentskill.adoc. - Wire the new page through scripts/render-docs.js, scripts/prerender-routes.js, website/src/main.js (renderSocraticRecoverySkillPage), and the route title map in website/src/utils/router.js. Reachable at /socratic-recovery-skill in both languages. - Add a [TIP] pointer from docs/brownfield-workflow.adoc (EN+DE) Phase 0.5 to the new skill page so users who reach the workflow find the install path immediately. - Add a "See also" entry to docs/agentskill.adoc (EN+DE) so the existing AgentSkill page also surfaces the new skill. - Add a [NOTE] callout at the top of docs/spec-driven-workflow.adoc (EN+DE) pointing brownfield users to the Brownfield Workflow and the skill — previously brownfield was only discoverable at the very bottom of the greenfield page. Build now pre-renders 14 routes (was 13). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fix: sync socratic-code-theory-recovery skill into plugin bundle (follow-up to #478)
2 participants
Closes #473
Summary
Packages the brownfield Socratic Code-Theory Recovery workflow as an installable Claude Code Skill at `skill/socratic-code-theory-recovery/`. Same packaging convention as the existing `semantic-anchor-translator` and `semantic-anchor-onboarding` skills.
Contents (9 files, 815 lines)
Reference snippets are embedded (per scope decision) rather than linked, so the skill is usable offline once installed.
Out of scope (deferred to follow-up issues)
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Dokumentation