@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plan-build-run/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
+- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
+- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
+
+A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+- Headers longer than 12 characters (hard limit — validation will reject them)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+**Tip for users — modifying an option:**
+Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
+
+</using_askuserquestion>
+
+<freeform_rule>
+
+**When the user wants to explain freely, STOP using AskUserQuestion.**
+
+If a user selects "Other" and their response signals they want to describe something in their own words (e.g., "let me describe it", "I'll explain", "something else", or any open-ended reply that isn't choosing/modifying an existing option), you MUST:
+
+1. **Ask your follow-up as plain text** — NOT via AskUserQuestion
+2. **Wait for them to type at the normal prompt**
+3. **Resume AskUserQuestion** only after processing their freeform response
+
+The same applies if YOU include a freeform-indicating option (like "Let me explain" or "Describe in detail") and the user selects it.
+
+**Wrong:** User says "let me describe it" → AskUserQuestion("What feature?", ["Feature A", "Feature B", "Describe in detail"])
+**Right:** User says "let me describe it" → "Go ahead — what are you thinking?"
+
+</freeform_rule>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear PROJECT.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>

package/plan-build-run/references/reading-verification.md

@@ -0,0 +1,127 @@
+# Reading Verification Reports
+
+A user-friendly guide to understanding verification results.
+
+---
+
+## What Verification Checks
+
+After building a phase, Plan-Build-Run runs automated verification to check whether the code actually delivers what was planned. It checks every "must-have" from the plan through three layers:
+
+### Layer 1: Existence
+
+**Question**: Does the file/function/route exist at all?
+
+This is the most basic check. If the plan said "create `src/auth.ts`" — does that file exist on disk? If it said "add a `/login` route" — can we find it in the codebase?
+
+**Common failures**: File was planned but never created, renamed to a different path, or deleted by a later task.
+
+### Layer 2: Substantiveness
+
+**Question**: Is the code real, or just a stub/placeholder?
+
+A file can exist but contain nothing useful — an empty function, a `throw new Error('Not implemented')`, or a component that just renders its own name. This layer catches those cases.
+
+**Common failures**: Function body is empty, returns hardcoded test data, or only has a TODO comment.
+
+### Layer 3: Wiring
+
+**Question**: Are the pieces connected to each other?
+
+Code can exist and be real, but if nothing imports it or calls it, it's dead code. This layer checks that modules are imported where needed, middleware is applied to routes, and components are rendered in the right places.
+
+**Common failures**: Module created but never imported, route handler exists but not registered in the router, component built but not used in any page.
+
+---
+
+## Reading the Verification Report
+
+A `VERIFICATION.md` file looks like this:
+
+```
+Status: passed (or gaps_found)
+Must-haves checked: 8
+Passed: 7
+Gaps: 1
+```
+
+### When status is "passed"
+
+All must-haves passed all three layers. The phase is complete and you can move on.
+
+### When status is "gaps_found"
+
+One or more must-haves failed verification. Each gap includes:
+
+- **Must-have**: What was expected (from the plan)
+- **Failed layer**: Which check failed (existence, substantiveness, or wiring)
+- **Evidence**: The specific command output or file content that shows the failure
+- **Suggested fix**: What to do about it
+
+---
+
+## Common Gap Types and What They Mean
+
+### "File not found"
+**Layer**: Existence
+**Meaning**: A planned file was never created or was created at a different path.
+**Fix**: Usually a simple oversight — the executor may have created it with a slightly different name. Check the phase directory for similar files.
+
+### "Function is a stub"
+**Layer**: Substantiveness
+**Meaning**: The file exists but the implementation is incomplete. Common indicators: empty function bodies, `TODO` comments, placeholder return values.
+**Fix**: The executor may have run out of context before finishing. Re-running the build usually resolves this.
+
+### "Module not imported"
+**Layer**: Wiring
+**Meaning**: The code was written correctly but nothing uses it. The import statement is missing from the consuming file.
+**Fix**: Usually a one-line fix — add the import statement to the right file.
+
+### "Test has no assertions"
+**Layer**: Substantiveness
+**Meaning**: A test file exists but doesn't actually test anything — empty `it()` blocks or `expect(true).toBe(true)`.
+**Fix**: Real test assertions need to be written. This usually happens when TDD mode is off and the executor generates placeholder tests.
+
+### "Route not registered"
+**Layer**: Wiring
+**Meaning**: A route handler function was created but never mounted on the Express/Fastify/etc. router.
+**Fix**: Add the route registration (usually `app.use()` or `router.get()`) to the main app file.
+
+---
+
+## How to Close Gaps
+
+You have several options:
+
+### Option 1: Re-run the build (most common)
+```
+/pbr:execute-phase <N>
+```
+The executor will detect what's already complete and only fix what's missing.
+
+### Option 2: Create a gap-closure plan
+```
+/pbr:plan-phase <N> --gaps
+```
+This creates a focused plan that targets only the specific gaps found during verification.
+
+### Option 3: Manual fix
+For small gaps (like a missing import), you can fix the code yourself and then re-run verification:
+```
+/pbr:verify-work <N>
+```
+
+### Option 4: Override (for false positives)
+If verification flagged something that's actually correct (e.g., a function intentionally returns an empty array), you can override the gap during review. The override is recorded in the verification report.
+
+---
+
+## Understanding Verification Attempts
+
+The verification report tracks `attempt` count. If a phase has been verified multiple times:
+
+- **Attempt 1**: Normal first verification
+- **Attempt 2**: Gaps were found and fixed, re-verifying
+- **Attempt 3+**: Escalation — Plan-Build-Run will offer additional options like accepting with gaps, switching to debug mode, or re-planning the phase
+
+Multiple attempts don't mean something is wrong — complex phases often need a round of gap-closure before passing.

package/plan-build-run/references/stub-patterns.md

@@ -0,0 +1,160 @@
+# Stub Detection Patterns
+
+Technology-aware patterns for detecting incomplete implementations. Used by the verifier during Layer 2 (Substantiveness) checks.
+
+Read the project's stack from `.planning/codebase/STACK.md` or `.planning/research/STACK.md` to determine which technology-specific patterns to apply. If no stack file exists, use universal patterns only.
+
+---
+
+## Universal Patterns (always check)
+
+- TODO, FIXME, HACK, PLACEHOLDER, "not implemented"
+- `return null`, `return {}`, `return []`, `return undefined`
+- Empty function bodies, functions that only console.log
+- `throw new Error('Not implemented')` or similar
+- Placeholder strings ("lorem ipsum", "sample data", "example")
+
+## React/Next.js Patterns (when stack includes React/Next)
+
+- `<div>ComponentName</div>` — component returning only its name
+- `onClick={() => {}}` — empty event handlers
+- `fetch()` without error handling or response processing
+- `useState` with no state updates
+- Components returning `null`, `<></>`, or single placeholder div
+
+## API/Express Patterns (when stack includes Express/Fastify/Koa)
+
+- `res.json({ message: "Not implemented" })`
+- Empty middleware: `(req, res, next) => next()`
+- Routes returning hardcoded test data
+- `res.status(501)` responses
+
+## Database Patterns (when stack includes any ORM/database)
+
+- Empty migration files
+- Models/schemas with no fields beyond id
+- Repository methods that return empty arrays
+
+## Python Patterns (when stack includes Python)
+
+- `pass` in function bodies
+- `raise NotImplementedError`
+- Functions returning `None` without logic
+- `# TODO` in function bodies
+
+## Go Patterns (when stack includes Go)
+
+- Functions returning zero values without logic
+- `panic("not implemented")`
+- Empty interface implementations
+
+---
+
+## Detailed Examples
+
+### TypeScript/JavaScript Stubs
+
+```typescript
+// STUB PATTERN: Empty function body
+export function processData() { }
+export function processData() { return; }
+export function processData() { return null; }
+export const processData = () => {};
+
+// STUB PATTERN: Placeholder implementation
+export function processData() {
+  throw new Error('Not implemented');
+}
+export function processData() {
+  throw new Error('TODO');
+}
+
+// STUB PATTERN: Hardcoded return value
+export function getUsers(): User[] {
+  return [];
+}
+export function getConfig(): Config {
+  return {} as Config;
+}
+
+// STUB PATTERN: Console.log instead of implementation
+export function saveUser(user: User): void {
+  console.log('TODO: implement saveUser', user);
+}
+
+// STUB PATTERN: Pass-through without logic
+export function validateInput(input: unknown): boolean {
+  return true;  // Always passes - no real validation
+}
+```
+
+### React Component Stubs
+
+```tsx
+// STUB: Null return
+export function Dashboard() { return null; }
+
+// STUB: Empty fragment
+export function Dashboard() { return <></>; }
+
+// STUB: Placeholder text
+export function Dashboard() { return <div>Dashboard</div>; }
+export function Dashboard() { return <div>Coming soon</div>; }
+
+// STUB: Div with just the name
+export function UserProfile() { return <div>UserProfile</div>; }
+
+// REAL (NOT a stub): Has actual JSX structure with data binding
+export function Dashboard({ data }: Props) {
+  return (
+    <div className="dashboard">
+      <h1>{data.title}</h1>
+      <MetricsGrid metrics={data.metrics} />
+    </div>
+  );
+}
+```
+
+### API Route/Handler Stubs
+
+```typescript
+// STUB: Empty response
+app.get('/api/users', (req, res) => { res.json({}); });
+
+// STUB: Not implemented status
+app.get('/api/users', (req, res) => { res.status(501).json({ error: 'Not implemented' }); });
+
+// STUB: Hardcoded test data
+app.get('/api/users', (req, res) => {
+  res.json([{ id: 1, name: 'Test User' }]);
+});
+
+// REAL: Database query, error handling, response
+app.get('/api/users', async (req, res) => {
+  const { page = 1, limit = 20 } = req.query;
+  const users = await db.users.findMany({ skip: (page - 1) * limit, take: limit });
+  res.json({ data: users, page, limit });
+});
+```
+
+### Test Stubs
+
+```typescript
+// STUB: No assertions
+it('should process data', () => {});
+
+// STUB: Trivial assertion
+it('should process data', () => { expect(true).toBe(true); });
+
+// STUB: Skipped
+it.skip('should process data', () => { /* ... */ });
+xit('should process data', () => { /* ... */ });
+
+// REAL: Actual test with meaningful assertions
+it('should process data and return transformed result', () => {
+  const input = createTestData();
+  const result = processData(input);
+  expect(result.items).toHaveLength(3);
+  expect(result.total).toBe(150);
+});
+```