know-thy-build 0.3.0 → 0.3.2

package/README.md

@@ -136,6 +136,45 @@ Supported shortcuts: `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt` — or pass
 
 All conversation and generated documents use the chosen language. Technical terms stay in English.
 
+## Foundations
+
+know-thy-build draws on established techniques from philosophy, software engineering, and AI research.
+
+### Core method: Socratic Prompting
+
+The tool applies the [Socratic method](https://en.wikipedia.org/wiki/Socratic_method) — questioning to surface latent knowledge rather than providing answers directly. In Plato's *Meno*, Socrates demonstrates that learning is **recollection** (anamnesis): the right questions draw out what the learner already knows. know-thy-build operates on the same premise — you already know what you want to build, you just haven't articulated it yet.
+
+- Chang, ["Prompting Large Language Models With the Socratic Method"](https://arxiv.org/abs/2303.08769) (2023) — adapts Socratic strategies into LLM prompting templates
+- Princeton NLP, ["The Socratic Method for Self-Discovery in Large Language Models"](https://princeton-nlp.github.io/SocraticAI/) — explicitly connects Socratic dialogue to self-discovery in LLMs
+- [SocraticLM](https://proceedings.neurips.cc/paper_files/paper/2024/hash/9bae399d1f34b8650351c1bd3692aeae-Abstract-Conference.html) (NeurIPS 2024 Spotlight) — Socratic teaching paradigm outperforming GPT-4 by >12%
+
+### Dialectical reasoning
+
+Each exchange follows a thesis-antithesis-synthesis cycle: the user states what they want (thesis), the tool challenges it (antithesis), and a refined understanding emerges (synthesis). This is [Hegelian dialectic](https://en.wikipedia.org/wiki/Dialectic#Hegelian_dialectic) applied to project definition.
+
+- ["Self-reflecting LLMs: A Hegelian Dialectical Approach"](https://arxiv.org/abs/2501.14917) (2025)
+
+### Requirements elicitation
+
+In software engineering, [requirements elicitation](https://en.wikipedia.org/wiki/Requirements_elicitation) is the process of discovering what stakeholders actually need — a discipline that recognizes requirements are *discovered*, not merely captured.
+
+- Zave & Jackson, "Four Dark Corners of Requirements Engineering" (1997, ACM TOSEM)
+- ["AI-based Multiagent Approach for Requirements Elicitation and Analysis"](https://arxiv.org/abs/2409.00038) (2024)
+
+### Design Thinking (Define phase)
+
+know-thy-build's output maps to the **Define** phase of [Design Thinking](https://web.stanford.edu/~mshanks/MichaelShanks/files/509554.pdf) (Stanford d.school) — synthesizing fuzzy intuitions into a structured problem statement that guides everything that follows.
+
+### The Rubber Duck, upgraded
+
+[Rubber duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging) works because articulating forces clarity. know-thy-build is a rubber duck that talks back — one that not only forces articulation but actively probes weak spots and challenges surface-level answers.
+
+### Multi-Agent Debate
+
+Even within a single facilitator, know-thy-build adopts multiple perspectives — questioning like a PM, challenging like an architect, probing edge cases like QA. The principle that opposing viewpoints produce better outcomes is well-established.
+
+- Liang et al., ["Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate"](https://arxiv.org/abs/2305.19118) (EMNLP 2024)
+
 ## License
 
 MIT

package/bin/cli.js

@@ -7,6 +7,7 @@ import {
   writeFileSync,
   readdirSync,
   statSync,
+  unlinkSync,
 } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -87,14 +88,32 @@ function installDir(srcDir, destDir, lang) {
   }
 }
 
+const LEGACY_FILES = ["know-thy-build.md", "know-thy-build-evolve.md"];
+
+function cleanLegacy(commandsDir) {
+  let cleaned = [];
+  for (const file of LEGACY_FILES) {
+    const filePath = join(commandsDir, file);
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+      cleaned.push(file);
+    }
+  }
+  return cleaned;
+}
+
 function install(lang, global) {
   const commandsDir = global
     ? join(homedir(), ".claude", "commands")
     : join(process.cwd(), ".claude", "commands");
 
+  const cleaned = cleanLegacy(commandsDir);
   installDir(templatesDir, commandsDir, lang);
 
   const scope = global ? "globally (~/.claude/commands/)" : "in this project";
+  if (cleaned.length > 0) {
+    console.log(`\n  Cleaned up legacy commands: ${cleaned.join(", ")}`);
+  }
   console.log(`
   Done! Installed ${scope} (${lang})
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Socratic project definition tool for Claude Code",
   "bin": {
     "know-thy-build": "./bin/cli.js"

package/templates/know-thy-build/feature.md

@@ -67,21 +67,29 @@ Find the highest existing number and increment by 1. Zero-pad to 3 digits. If `f
 
 These are NOT a rigid sequence. Follow the conversation. Most features only need 2-3 of these to be clear.
 
-#### What — What are we building?
+#### Problem — What's broken or missing?
 
-> Discover: The concrete thing to implement.
+> Discover: The specific pain this feature addresses. This is not the project-level problem (that's in PROJECT.md) — this is the concrete gap or friction that triggered "we need this feature."
 
-- What does this feature do, in one sentence?
-- What does the user see/experience when it's working?
-- Is there an existing pattern in the codebase this builds on?
+- What's not working right now? What's the user struggling with?
+- What happens today without this feature? (workaround, manual step, error, confusion...)
+- Who hits this problem and how often?
 
-#### Why — Why does this matter?
+#### Value — Why is this worth building?
 
-> Discover: The motivation. Link to PROJECT.md if relevant.
+> Discover: The value this feature delivers and how it connects to the bigger picture.
 
-- What problem does this solve or what value does it add?
-- What happens if we don't build it?
-- Does this connect to a principle or vision in PROJECT.md?
+- What changes for the user when this exists?
+- How does this connect to the project's vision or principles in PROJECT.md?
+- What happens if we don't build it? Is there a cost of inaction?
+
+#### Solution — How does this solve it?
+
+> Discover: The concrete thing to implement. Not implementation details, but the user-facing shape of the solution.
+
+- What does this feature do, in one sentence?
+- What does the user see/experience when it's working?
+- Is there an existing pattern in the codebase this builds on?
 
 #### Scope — Where are the edges?
 
@@ -148,13 +156,17 @@ During conversation, use `status: drafting`. On finalization, set to `complete`.
 
 <!-- One-liner: what this feature does -->
 
-## What
+## Problem
+
+<!-- What's broken or missing today. The specific pain this feature addresses. -->
+
+## Value
 
-<!-- Concrete description of what gets built -->
+<!-- What changes when this exists. Link to PROJECT.md vision/principles if relevant. -->
 
-## Why
+## Solution
 
-<!-- Motivation. Reference PROJECT.md if relevant -->
+<!-- Concrete description of what gets built and how the user experiences it -->
 
 ## Scope