Skip to content

Commit b0a2ebd

Browse files
raifdmuellerclaude
andcommitted
docs(skill): add on-invocation guard to socratic-code-theory-recovery
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) <noreply@anthropic.com>
1 parent d9190c2 commit b0a2ebd

2 files changed

Lines changed: 28 additions & 0 deletions

File tree

  • plugins/semantic-anchors/skills/socratic-code-theory-recovery
  • skill/socratic-code-theory-recovery

plugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.md

Lines changed: 14 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

skill/socratic-code-theory-recovery/SKILL.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,20 @@ license: MIT
1212

1313
Reverse-engineer a bounded context into documentation without hallucinating the parts the code cannot tell you.
1414

15+
## On invocation
16+
17+
When this skill is invoked:
18+
19+
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.
20+
21+
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:
22+
23+
> 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.
24+
25+
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.
26+
27+
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.
28+
1529
## When to use this skill
1630

1731
Use this skill on a brownfield codebase when:

0 commit comments

Comments
 (0)