@vpxa/aikit 0.1.186 → 0.1.187

package/scaffold/dist/definitions/skills/lesson-learned.mjs

@@ -164,7 +164,7 @@ Code signals: A switch/if-else chain replaced with a strategy pattern or subclas
 Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.
 `},{file:`SKILL.md`,content:`---
 name: lesson-learned
-description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
+description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', 'what principles does this show?', or wants to extract actionable insights from recent work. Also use after completing any implementation task to capture learning."
 metadata:
   category: cross-cutting
   domain: general
@@ -177,17 +177,22 @@ metadata:
 
 # Lesson Learned
 
-Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
+Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates, and only elevate lessons that are earned by the diff.
 
 ## Before You Begin
 
-**Load the principles reference first.**
+- Determine the analysis scope first.
+- Use the inline principles below for the common case.
+- Read 'references/se-principles.md' only when the dominant pattern is unclear or you need a deeper principle match.
+- Read 'references/anti-patterns.md' only when the diff suggests a gentle improvement opportunity.
 
-1. Read \`references/se-principles.md\` to have the principle catalog available
-2. Optionally read \`references/anti-patterns.md\` if you suspect the changes include areas for improvement
-3. Determine the scope of analysis (see Phase 1)
+## Core Principles
 
-**Do not proceed until you've loaded at least \`se-principles.md\`.**
+- **SRP** -- one module, one reason to change. Diff signal: a file/function was split because it was carrying mixed responsibilities.
+- **Separation of Concerns** -- keep UI, domain, data, config, and orchestration in their own lanes. Diff signal: logic moved across a boundary into a more appropriate layer.
+- **YAGNI** -- build only what current requirements justify. Diff signal: speculative abstractions, options, or branches were removed or avoided.
+- **Fail Fast** -- detect bad input or invalid state at the boundary. Diff signal: guards, validation, assertions, or early returns were added near the entry point.
+- **DRY** -- shared knowledge should live in one place. Diff signal: duplicated literals, branches, or helper logic were consolidated into one source.
 
 ## Phase 1: Determine Scope
 
@@ -207,23 +212,46 @@ Ask the user or infer from context what to analyze.
 
 ## Phase 2: Gather Changes
 
-1. Run \`git log\` with the determined scope to get the commit list and messages
-2. Run \`git diff\` for the full diff of the scope
-3. If the diff is large (>500 lines), use \`git diff --stat\` first, then selectively read the top 3-5 most-changed files
-4. **Read commit messages carefully** -- they contain intent that raw diffs miss
-5. Only read changed files. Do not read the entire repo.
+1. Run \`git log\` with the determined scope to get commits and messages.
+2. Run \`git diff\` for the full diff of that scope.
+3. If the diff is large (>500 lines), start with \`git diff --stat\`, then inspect the 3-5 most-changed files.
+4. Read commit messages carefully -- they often reveal intent that raw diffs do not.
+5. Only read changed files. Do not widen scope beyond the diff.
+6. Capture concrete evidence as you go: commit SHA, file path, and line references.
 
 ## Phase 3: Analyze
 
-Identify the **dominant pattern** -- the single most instructive thing about these changes.
+Apply this decision tree to find the dominant lesson:
 
-Look for:
-- **Structural decisions** -- How was the code organized? Why those boundaries?
-- **Trade-offs made** -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)
-- **Problems solved** -- What was the before/after? What made the "after" better?
-- **Missed opportunities** -- Where could the code improve? (present gently as "next time, consider...")
+1. **Is there a structural change?** (files split/merged, new module boundary, layer introduced)
+  -> Lesson is about architecture principles (SRP, Separation of Concerns, Cohesion)
 
-Map findings to specific principles from \`references/se-principles.md\`. Be specific -- quote actual code, reference actual file names and line changes.
+2. **Is there a removed or simplified path?** (deleted code, simplified conditionals, fewer dependencies)
+  -> Lesson is about simplicity principles (YAGNI, KISS, Premature Abstraction avoidance)
+
+3. **Is there error handling or edge case work?** (try/catch added, validation, fallbacks)
+  -> Lesson is about robustness principles (Fail Fast, Defensive Programming)
+
+4. **Is there duplication resolved?** (extracted shared logic, parameterized, DRY applied)
+  -> Lesson is about DRY and Rule of Three
+
+5. **Is there a naming or API change?** (renames, interface changes, contract adjustments)
+  -> Lesson is about Principle of Least Surprise and Encapsulation
+
+6. **None of the above clearly dominate?**
+  -> The changes may be routine. Check commit messages for unstated intent. If still nothing emerges, be honest that no deep lesson exists.
+
+For the dominant pattern, map to the specific principle from \`references/se-principles.md\` when needed and cite the concrete code change that demonstrates it.
+
+## Quality Gate
+
+A lesson is only worth presenting if ALL of these are true:
+- **Non-obvious** -- someone reading the diff would not immediately see it without prompting
+- **Actionable** -- it changes future behavior, not just "interesting observation"
+- **Specific** -- cites actual file:line, not generic advice
+- **Earned** -- emerges naturally from the code, not force-fit to a principle
+
+If no lesson meets all four criteria, say so honestly: "These changes are solid execution -- no deep lesson here beyond good engineering practice."
 
 ## Phase 4: Present the Lesson
 
@@ -245,7 +273,7 @@ Use this template:
 [One concrete, actionable sentence the user can apply to future work]
 \`\`\`
 
-If there is a second lesson worth noting (maximum 2 additional):
+If there is a second lesson worth noting, include at most one more:
 
 \`\`\`markdown
 ---
@@ -257,6 +285,8 @@ If there is a second lesson worth noting (maximum 2 additional):
 **Takeaway:** [1 sentence]
 \`\`\`
 
+Do not present more than 2 lessons total. If the diff is mostly clean execution with no deeper pattern, say that directly.
+
 ## What NOT to Do
 
 | Avoid | Why | Instead |
@@ -266,7 +296,17 @@ If there is a second lesson worth noting (maximum 2 additional):
 | Ignoring commit messages | They contain intent that diffs miss | Read them as primary context |
 | Abstract advice disconnected from the code | Not actionable | Always reference specific files/lines |
 | Negative-only feedback | Demoralizing | Lead with what works, then suggest improvements |
-| More than 3 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
+| More than 2 lessons | Dilutes the insight | One well-grounded lesson beats seven vague ones |
+
+## NEVER
+
+- **NEVER present obvious refactoring as a lesson** ("the code got cleaner") -- this is table stakes, not insight
+- **NEVER force-fit a principle** that does not naturally emerge from the diff -- if you have to stretch to connect code to principle, the connection is not there
+- **NEVER produce more than 2 lessons** per analysis -- one well-grounded insight beats seven vague observations
+- **NEVER use "best practice" without citing WHICH practice and WHY it is best HERE** -- "best practice" is the refuge of those who cannot explain the reasoning
+- **NEVER analyze files that were not changed** -- scope creep dilutes focus
+- **NEVER start with criticism** -- lead with what the code demonstrates well, then optionally note opportunities
+- **NEVER produce a lesson without a concrete code reference** -- if you cannot point to a specific line or commit, the lesson is too abstract
 
 ## Conversation Style
 

package/scaffold/dist/definitions/skills/react.mjs

@@ -22,18 +22,84 @@ metadata:
 - Optimizing React performance (re-renders, bundle size, data fetching)
 - Reviewing React code for correctness and best practices
 
+## Thinking Model
+
+React is a **description language for UI**, not an imperative framework. Think in snapshots, not steps:
+- "Given this state, what should the screen look like?" (declarative)
+- NOT "When this happens, do these 5 things in order" (imperative)
+
+The render function is a PURE function of (props, state) → JSX. Side effects live in clearly-marked boundaries (effects, event handlers, server actions).
+
+**Server vs Client boundary** — the most common architectural mistake in modern React:
+- Default to Server Components (zero JS shipped, direct data access)
+- Add 'use client' only when you need: event handlers, useState/useEffect, browser APIs
+- The boundary is a CONTRACT — server can render client, client CANNOT import server
+
+Before coding, decide in this order:
+1. **What is pure UI derivation?** Keep it in render.
+2. **What is interaction state?** Keep it in the smallest client boundary.
+3. **What is data loading or mutation?** Prefer server.
+4. **What is side effect vs event response?** Effects synchronize with outside systems; event handlers respond to user intent.
+
+## Decision Flow
+
+When implementing a React feature, follow this order:
+
+1. **Server or Client?**
+  - If it needs browser APIs, event handlers, or local interaction state → Client Component.
+  - Everything else starts as a Server Component.
+  - Keep the client boundary as small as possible: interactive leaf, server parent.
+
+2. **Derived state or stored state?**
+  - If a value can be computed from props/state during render, do NOT store it.
+  - Store only user input, async status, or state you cannot recompute cheaply or correctly.
+
+3. **Data loading location?**
+  - Initial fetch on server.
+  - Client refetch/cache only when data must stay live after hydration or respond to client events.
+
+4. **Mutation path?**
+  - Forms and mutations: Server Action + validation.
+  - Use \`useActionState\` for submission state/errors.
+  - Add \`useOptimistic\` only when instant feedback materially improves UX.
+
+5. **Effect or not?**
+  - If synchronizing with DOM, network subscription, timer, or external API → effect.
+  - If reacting to user input → event handler.
+  - If deriving view state → render logic, not effect.
+
+6. **Error and loading boundaries?**
+  - Rendering latency → \`<Suspense>\` with a real skeleton.
+  - Render failures → Error Boundary.
+  - Mutation failures → return structured errors from the Server Action.
+
+7. **Performance pass?**
+  - Start with correct boundaries and minimal client JS.
+  - Then rely on React Compiler if enabled.
+  - Only then add manual memoization, virtualization, or code splitting where profiling justifies it.
+
+8. **Extraction pass?**
+  - Business rules → hooks, utilities, or server functions.
+  - Components stay focused on describing UI.
+
+## NEVER
+
+- **NEVER use \`useEffect\` for derived state** — if you can compute it from props/state, compute it inline or with \`useMemo\`. Effects for derivation cause extra renders and race conditions.
+- **NEVER put business logic in components** — components are UI description, not business rules. Extract logic to hooks, utilities, or server functions.
+- **NEVER use \`any\` to silence TypeScript in component props** — use \`unknown\` and narrow, or fix the actual type. \`any\` in props infects the entire component tree.
+- **NEVER create a context for state that only one component reads** — prop drilling 2-3 levels is fine. Context adds re-render cost to EVERY consumer.
+- **NEVER \`await\` inside \`useEffect\` directly** — use an inner async function or a data-fetching library. Direct await creates unhandled promise rejections and races.
+- **NEVER conditionally call hooks** — hooks must be called in the same order every render. If you need conditional logic, move it INSIDE the hook.
+- **NEVER spread props onto DOM elements without filtering** — \`{...props}\` passes unknown attributes to the DOM, causing console warnings and potential XSS vectors.
+- **NEVER render a list without a stable key** — index-as-key causes state corruption on reorder. Use a domain ID or generate a stable key from content.
+
 ## React 19 Quick Reference
 
-| API | Use Case | Key Change |
-|-----|----------|------------|
-| \`ref\` as prop | Access DOM/component instance | No more \`forwardRef\` wrapper |
-| \`use()\` | Read promises/context in render | Replaces \`useContext\`, enables async |
-| \`useActionState\` | Form submission state + error | Replaces \`useFormState\` |
-| \`useOptimistic\` | Instant UI feedback | Optimistic updates before server confirms |
-| \`useTransition\` | Non-urgent state updates | \`isPending\` for loading states |
-| \`<form action>\` | Server Actions in forms | Direct server function binding |
-| Server Components | Zero-bundle components | Default in App Router, no \`"use client"\` |
-| Server Actions | Server mutations | \`"use server"\` functions, form actions |
+- \`ref\` as prop — no \`forwardRef\` wrapper for common cases
+- \`use()\` — read promises/context during render
+- \`useActionState\` + \`<form action>\` — form mutations with server actions
+- \`useOptimistic\` + \`useTransition\` — optimistic and non-urgent updates
+- Server Components / Server Actions — default to server, opt into client only when needed
 
 ## Component Patterns
 
@@ -77,56 +143,36 @@ function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }:
 \`\`\`
 
 ### Children Typing
-\`\`\`tsx
-// Specific children
-type Props = { children: React.ReactElement<TabProps>[] };
-
-// Render function children
-type Props = { children: (data: T) => React.ReactNode };
-
-// String only
-type Props = { children: string };
-\`\`\`
+- Specific children: \`React.ReactElement<TabProps>[]\`
+- Render prop: \`(data: T) => React.ReactNode\`
+- Text-only API: \`string\`
 
 ## Ref as Prop (React 19)
 
 \`\`\`tsx
-// React 19: pass ref directly, no forwardRef needed
 function Input({ ref, ...props }: React.ComponentProps<"input">) {
   return <input ref={ref} {...props} />;
 }
-
-// Cleanup function (new in React 19)
-function MeasuredDiv({ ref, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      ref={(node) => {
-        if (node) measureElement(node);
-        return () => cleanupMeasurement(); // cleanup on unmount
-      }}
-      {...props}
-    />
-  );
-}
 \`\`\`
 
+Callback refs can return cleanup functions in React 19. Use that for measurement/subscription teardown instead of scattering cleanup elsewhere.
+
 ## Server Components & Actions
 
 ### Server Component (default — no directive needed)
 \`\`\`tsx
-// app/users/page.tsx — Server Component (default)
 import { db } from "@/lib/db";
 
 export default async function UsersPage() {
-  const users = await db.query.users.findMany();  // Direct DB access
-  return <UserList users={users} />;  // Pass data to client
+  const users = await db.query.users.findMany();
+  return <UserList users={users} />;
 }
 \`\`\`
 
 ### Client Component (explicit opt-in)
 \`\`\`tsx
 "use client";
-import { useState, useOptimistic, useTransition } from "react";
+import { useState } from "react";
 
 export function Counter({ initialCount }: { initialCount: number }) {
   const [count, setCount] = useState(initialCount);
@@ -136,7 +182,6 @@ export function Counter({ initialCount }: { initialCount: number }) {
 
 ### Server Action with Form
 \`\`\`tsx
-// actions.ts
 "use server";
 import { z } from "zod";
 
@@ -145,7 +190,7 @@ const schema = z.object({ name: z.string().min(1), email: z.string().email() });
 export async function createUser(_prev: unknown, formData: FormData) {
   const result = schema.safeParse(Object.fromEntries(formData));
   if (!result.success) return { error: result.error.flatten().fieldErrors };
-  await db.insert(users).values(result.data);
+  await saveUser(result.data);
   return { success: true };
 }
 \`\`\`
@@ -160,9 +205,7 @@ export function CreateUserForm() {
   return (
     <form action={action}>
       <input name="name" required />
-      {state?.error?.name && <p className="text-red-500">{state.error.name}</p>}
       <input name="email" type="email" required />
-      {state?.error?.email && <p className="text-red-500">{state.error.email}</p>}
       <button disabled={isPending}>{isPending ? "Creating..." : "Create"}</button>
     </form>
   );
@@ -175,10 +218,10 @@ export function CreateUserForm() {
 import { useOptimistic } from "react";
 
 function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) => Promise<void> }) {
-  const [optimisticTodos, addOptimistic] = useOptimistic(
-    todos,
-    (state, newTodo: string) => [...state, { id: "temp", text: newTodo, pending: true }]
-  );
+  const [optimisticTodos, addOptimistic] = useOptimistic(todos, (state, text: string) => [
+    ...state,
+    { id: "temp", text, pending: true },
+  ]);
 
   async function handleAdd(formData: FormData) {
     const text = formData.get("text") as string;
@@ -202,109 +245,33 @@ function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) =
 
 ## Event Handler Types
 
-\`\`\`tsx
-// Always use specific event types
-onClick:    (e: React.MouseEvent<HTMLButtonElement>) => void
-onChange:   (e: React.ChangeEvent<HTMLInputElement>) => void
-onSubmit:   (e: React.FormEvent<HTMLFormElement>) => void
-onKeyDown:  (e: React.KeyboardEvent<HTMLInputElement>) => void
-onFocus:    (e: React.FocusEvent<HTMLInputElement>) => void
-onDrag:     (e: React.DragEvent<HTMLDivElement>) => void
-\`\`\`
+Prefer exact DOM event types at the boundary: \`MouseEvent<HTMLButtonElement>\`, \`ChangeEvent<HTMLInputElement>\`, \`FormEvent<HTMLFormElement>\`. If you start with a broad \`SyntheticEvent\`, you are probably typing too late.
 
 ## Hooks Typing
 
-\`\`\`tsx
-// useState with union
-const [status, setStatus] = useState<"idle" | "loading" | "error">("idle");
-
-// useRef for DOM — pass null, get RefObject
-const inputRef = useRef<HTMLInputElement>(null);
-
-// useRef for mutable value — no null, get MutableRefObject
-const intervalRef = useRef<number>(0);
-
-// useReducer with discriminated actions
-type Action = { type: "increment" } | { type: "set"; payload: number };
-const [count, dispatch] = useReducer((state: number, action: Action) => {
-  switch (action.type) {
-    case "increment": return state + 1;
-    case "set": return action.payload;
-  }
-}, 0);
-
-// Custom hook: return as const for tuple types
-function useToggle(initial = false) {
-  const [value, setValue] = useState(initial);
-  const toggle = useCallback(() => setValue(v => !v), []);
-  return [value, toggle] as const;
-}
-
-// useContext with null guard
-const ctx = useContext(ThemeContext);
-if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
-\`\`\`
+- \`useState\` — model UI state with explicit unions, not booleans that drift out of sync
+- \`useRef<HTMLInputElement>(null)\` for DOM refs; mutable refs only for non-render state
+- \`useReducer\` — discriminated union actions when state transitions are non-trivial
+- Custom hooks returning tuples should use \`as const\`
+- Context consumers should null-guard and fail fast outside their provider
 
 ## Performance Rules
 
 ### Prevent Async Waterfalls
 \`\`\`tsx
-// BAD — sequential fetching
 const user = await getUser(id);
-const posts = await getPosts(user.id);  // Waits for user first
-const comments = await getComments(posts[0].id);  // Waits for posts
+const posts = await getPosts(user.id);
 
-// GOOD — parallel where possible
 const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
 \`\`\`
 
-### Bundle Size
-- \`dynamic(() => import("./HeavyComponent"))\` — lazy load below-fold components
-- Tree-shake: use named exports, avoid \`import *\`
-- Analyze bundle: \`@next/bundle-analyzer\` to find bloat
-- Code-split by route — each page loads only its own JS
-- Avoid importing entire libraries: \`import { debounce } from "lodash-es"\` not \`import _ from "lodash"\`
-
-### Server-Side Performance
-- Default to Server Components — zero JS shipped to client
-- Stream with Suspense: wrap slow data fetchers in \`<Suspense fallback={<Skeleton />}>\`
-- Cache expensive computations with \`"use cache"\` directive
-- Avoid serializing large objects across server/client boundary
-
-### Client-Side Data Fetching
-- Use SWR or React Query — automatic caching, revalidation, error retry
-- Stale-while-revalidate: show cached data instantly, refresh in background
-- Error boundaries: \`<ErrorBoundary>\` wrapping data-dependent trees
-- Prefetch on hover/viewport for likely next navigations
-
-### Re-render Optimization
-- React Compiler (React 19): auto-memoizes — try this first before manual \`useMemo\`/\`useCallback\`
-- If no compiler: \`useMemo\` for expensive computations, \`useCallback\` for stable function references
-- Extract static JSX outside components — constants don't re-create
-- Split context: separate frequently-changing state from rarely-changing state
-- \`React.memo()\` on components receiving only primitive props
-
-### Rendering Performance
-- **Virtualize** lists > 100 items: \`@tanstack/react-virtual\`, \`react-window\`
-- Defer heavy computations with \`useDeferredValue\`
-- Batch state updates (React 18+ does this automatically in event handlers)
-- Avoid reading DOM layout during renders (force sync layout = jank)
-
-### Advanced Patterns
-- Progressive hydration: load and hydrate components as they enter viewport
-- Concurrent features: \`useTransition\` for non-blocking state updates
-- Suspense caching: combine \`<Suspense>\` with data cache for instant page transitions
-- React Compiler adoption: enable gradually, check for unsafe patterns first
-
-## Decision Flow
-
-When implementing a React feature:
+### Performance Checklist
+- Server Components first; ship less JS before optimizing JS
+- \`<Suspense>\` + streaming for slow server work
+- SWR/React Query when client data must stay fresh after hydration
+- React Compiler first, then manual \`useMemo\`/\`useCallback\` only when profiling proves need
+- Virtualize lists >100 items; defer heavy client work with \`useDeferredValue\`
+- Lazy load below-fold components; prefer named imports for tree-shaking
+- Avoid passing large objects across the server/client boundary
 
-1. **Server or Client?** → If it uses browser APIs, event handlers, or useState → Client. Everything else → Server.
-2. **Data fetching?** → Server Component for initial data. SWR/React Query for client-side mutations.
-3. **Form?** → Server Action + \`useActionState\` + Zod validation.
-4. **Optimistic?** → \`useOptimistic\` for instant feedback.
-5. **Loading?** → \`<Suspense>\` with skeleton fallback.
-6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
-7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.
 `}];export{e as default};

package/scaffold/dist/definitions/skills/requirements-clarity.mjs

@@ -1,6 +1,6 @@
 var e=[{file:`SKILL.md`,content:`---
 name: requirements-clarity
-description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
+description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), involve cross-team coordination, or when the user says 'I want to build...', 'add a feature for...', 'implement...', 'create a system that...'. Ask two core questions first - Why? (YAGNI check) and Simpler? (KISS check) - then score 0-100 until clarity reaches 90+. Critical for preventing rework on underspecified features.
 metadata:
   category: cross-cutting
   domain: general
@@ -20,6 +20,17 @@ Do NOT activate when:
 - Bug fixes with clear reproduction steps
 - Task is a single-file change with obvious scope
 
+## Mindset
+
+Requirements engineering is detective work, not stenography. Your job is NOT to write down what the user says - it's to uncover what they haven't said yet.
+
+The user knows their PROBLEM but often conflates it with a specific SOLUTION. Separate these. The problem is the requirement; the solution is a design decision.
+
+Before asking questions, mentally model:
+- **Stakeholders** - Who else cares? Who gets paged at 2am? Who pays?
+- **Failure modes** - What breaks? What's the blast radius? What's unrecoverable?
+- **Boundaries** - What's explicitly OUT of scope? What's "phase 2"?
+
 ## Protocol
 
 ### 1. YAGNI/KISS Gate
@@ -41,7 +52,39 @@ Assess the requirement against this rubric:
 | Implementation Completeness | /25 | Edge cases (8), error handling (9), data validation (8) |
 | Business Context | /20 | Problem statement (7), target users (7), success metrics (6) |
 
-If you present this rubric or a score update to the user, use \`present({ schemaVersion: 1, title: 'Requirements Clarity', blocks: [...] })\` with a \`metrics\` block for category scores and \`markdown\` or \`list\` blocks for follow-up notes. NEVER use \`code\` blocks for structured data or JSON.stringify() score payloads into markdown/code blocks.
+### Calibration Examples
+
+**Functional Clarity 10/10:**
+"User clicks Submit -> system validates email format (RFC 5322), checks uniqueness against users table, returns 201 with serialized user object (id, email, createdAt) or 422 with field-level errors array [{field, code, message}]"
+
+**Functional Clarity 3/10:**
+"User can sign up"
+
+**Technical Specificity 9/9 (constraints):**
+"Response time < 200ms p95 for all CRUD endpoints, PostgreSQL 16+, horizontal scaling via stateless workers behind ALB, no server-side sessions"
+
+**Technical Specificity 2/9:**
+"Should be fast and scalable"
+
+**Edge Cases 8/8:**
+"Empty input -> show inline validation before submit. Concurrent duplicate emails -> second request gets 409 Conflict. Network timeout -> client retries 3x with exponential backoff, then shows offline banner"
+
+**Edge Cases 2/8:**
+"Handle errors appropriately"
+
+### Expert Probing Techniques
+
+For each gap category, ask focused questions that reveal hidden requirements:
+
+**For edge cases:** Ask about empty states, concurrent access, partial failures, permission boundaries, rate limits, timezone/locale behavior, offline/degraded mode, data migration from existing state.
+
+**For error handling:** Ask "What happens when [external dependency] is down?", "What does the user see during a 30-second timeout?", "How does the system recover from partial writes?"
+
+**For integration points:** Ask "Who calls this?", "What calls does this make?", "What happens if the downstream service changes its contract?", "Is there a circuit breaker?"
+
+**For data validation:** Ask "What's the maximum size?", "What characters are allowed?", "What about Unicode/emoji?", "What happens with 0, null, negative numbers, MAX_INT?"
+
+**For business context:** Ask "Who loses money if this breaks?", "What's the rollback plan?", "How will you know this is working in production?"
 
 ### 3. Iterate Until ≥ 90
 
@@ -57,6 +100,16 @@ Prefer short, targeted questions over long questionnaires. Build on previous ans
 
 **HARD RULE:** Do not generate the requirements document with a score below 90.
 
+## NEVER
+
+- **NEVER accept vague acceptance criteria** like "it should work" or "user-friendly" - demand measurable outcomes (response time, error rate, specific user action -> specific system response)
+- **NEVER skip the YAGNI check** - 40% of requirements are premature. Ask "what happens if we ship without this?" first
+- **NEVER ask more than 3 questions per round** - cognitive overload causes shallow answers. Depth > breadth.
+- **NEVER accept "edge cases: handle errors appropriately"** - this means "I haven't thought about it." Push for specific scenarios.
+- **NEVER generate the document below score 90** - incomplete requirements cause more rework than taking time to clarify
+- **NEVER repeat questions the user already answered** - build on previous responses, reference what they said
+- **NEVER score above 80 without concrete acceptance criteria** - if you can't write a test for it, it's not a requirement
+
 ### 4. Generate Requirements Document
 
 **Output path (flow-aware):**