From b0a2ebd71d81b5348a13158c773703d8697512d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Thu, 14 May 2026 08:39:58 +0200 Subject: [PATCH] docs(skill): add on-invocation guard to socratic-code-theory-recovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill described the methodology but did not tell the LLM what to do the moment it is invoked. Result: invoking the slash command displayed the SKILL.md content, and Claude defaulted to a meta-conversation about the skill instead of starting Phase 1. The user has to know to either add the bounded-context path to the invoking message or chase it with a follow-up. Add a four-step "On invocation" section at the top of SKILL.md: 1. Check whether the user already named a bounded context (path + name). 2. If not, ask one specific question for it — do not assume the current working directory, because Phase 1 produces files and a wrong target wastes work. 3. Run Phase 1 with the user's path. 4. Stop after Phase 1; Phase 2 needs team answers and must not run silently in the same session. The pre-commit hook mirrors this into the plugin bundle. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../skills/socratic-code-theory-recovery/SKILL.md | 14 ++++++++++++++ skill/socratic-code-theory-recovery/SKILL.md | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md index 25ec944..29b0bd9 100644 --- a/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md +++ b/plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md @@ -12,6 +12,20 @@ license: MIT Reverse-engineer a bounded context into documentation without hallucinating the parts the code cannot tell you. +## On invocation + +When this skill is invoked: + +1. **Check whether the user named a bounded context.** Look at the same message that invoked the skill and at the immediately preceding messages. A valid bounded-context pointer is a path (relative or absolute) to a directory, plus a short human-readable name for what the context is (e.g. `src/auth`, "Authentication"). If both are present, proceed to Phase 1. + +2. **If no bounded context is named, ask for it before doing anything else.** Do not start Phase 1 against the current working directory by default — Phase 1 produces files (`QUESTION_TREE.adoc`, `OPEN_QUESTIONS.adoc`) and running it on the wrong directory wastes work. Ask exactly: + + > Which bounded context should I apply Socratic Code-Theory Recovery to? Give me a directory path (the bounded context's code root) and a short human-readable name. If you want the whole current repo treated as one bounded context, say so explicitly. + +3. **Once you have the pointer, run Phase 1.** Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md) — substitute `[bounded context path]` with the user's path. Do not change the leaf classification, Q-ID scheme, or output files. + +4. **Stop after Phase 1.** Phase 2 must wait for the team to answer the `[OPEN]` leaves in `OPEN_QUESTIONS.adoc`. Tell the user that Phase 1 is complete, where the two output files are, and what the next manual step is — do not proceed to Phase 2 in the same session unless the user explicitly asks. + ## When to use this skill Use this skill on a brownfield codebase when: diff --git a/skill/socratic-code-theory-recovery/SKILL.md b/skill/socratic-code-theory-recovery/SKILL.md index 25ec944..29b0bd9 100644 --- a/skill/socratic-code-theory-recovery/SKILL.md +++ b/skill/socratic-code-theory-recovery/SKILL.md @@ -12,6 +12,20 @@ license: MIT Reverse-engineer a bounded context into documentation without hallucinating the parts the code cannot tell you. +## On invocation + +When this skill is invoked: + +1. **Check whether the user named a bounded context.** Look at the same message that invoked the skill and at the immediately preceding messages. A valid bounded-context pointer is a path (relative or absolute) to a directory, plus a short human-readable name for what the context is (e.g. `src/auth`, "Authentication"). If both are present, proceed to Phase 1. + +2. **If no bounded context is named, ask for it before doing anything else.** Do not start Phase 1 against the current working directory by default — Phase 1 produces files (`QUESTION_TREE.adoc`, `OPEN_QUESTIONS.adoc`) and running it on the wrong directory wastes work. Ask exactly: + + > Which bounded context should I apply Socratic Code-Theory Recovery to? Give me a directory path (the bounded context's code root) and a short human-readable name. If you want the whole current repo treated as one bounded context, say so explicitly. + +3. **Once you have the pointer, run Phase 1.** Use [prompts/phase-1-question-tree.md](prompts/phase-1-question-tree.md) — substitute `[bounded context path]` with the user's path. Do not change the leaf classification, Q-ID scheme, or output files. + +4. **Stop after Phase 1.** Phase 2 must wait for the team to answer the `[OPEN]` leaves in `OPEN_QUESTIONS.adoc`. Tell the user that Phase 1 is complete, where the two output files are, and what the next manual step is — do not proceed to Phase 2 in the same session unless the user explicitly asks. + ## When to use this skill Use this skill on a brownfield codebase when: