productkit 1.7.0 → 1.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,8 @@ Slash-command-driven product thinking toolkit for [Claude Code](https://claude.c
 
 Product Kit gives PMs a structured workflow for validating product ideas — user personas, problem statements, assumptions mapping — all through guided AI conversations.
 
+**[Read the full guide →](https://iamquechua.github.io/product-kit/)**
+
 ## Prerequisites
 
 - **Node.js** 18 or later
@@ -43,6 +45,19 @@ cd my-project
 
 This scaffolds a project with slash commands, a `CLAUDE.md` context file, and a `.productkit/` config directory.
 
+For existing projects:
+
+```bash
+cd my-existing-project
+productkit init --existing
+```
+
+To keep artifacts out of the project root (recommended for busy codebases):
+
+```bash
+productkit init --existing --artifact-dir docs/product
+```
+
 ### 2. Open Claude Code
 
 ```bash
@@ -59,17 +74,20 @@ Each command starts a guided conversation. Claude asks questions, pushes back on
 | 2 | `/productkit.users` | Define target user personas through dialogue | `users.md` |
 | 3 | `/productkit.problem` | Frame the problem statement grounded in user research | `problem.md` |
 | 4 | `/productkit.assumptions` | Extract and prioritize hidden assumptions | `assumptions.md` |
-| 5 | `/productkit.solution` | Brainstorm and evaluate solution ideas | `solution.md` |
-| 6 | `/productkit.prioritize` | Score and rank features for v1 | `priorities.md` |
-| 7 | `/productkit.spec` | Generate a complete product spec | `spec.md` |
+| 5 | `/productkit.validate` | Validate assumptions with interviews and surveys | `validation.md` |
+| 6 | `/productkit.solution` | Brainstorm and evaluate solution ideas | `solution.md` |
+| 7 | `/productkit.prioritize` | Score and rank features for v1 | `priorities.md` |
+| 8 | `/productkit.spec` | Generate a complete product spec | `spec.md` |
 | — | `/productkit.clarify` | Resolve ambiguities and contradictions across artifacts | Updates existing files |
 | — | `/productkit.analyze` | Run a consistency and completeness check | Analysis in chat |
+| — | `/productkit.bootstrap` | Auto-draft all artifacts from existing codebase | All missing artifacts |
+| — | `/productkit.audit` | Compare spec against codebase, surface gaps | `audit.md` |
 
 Commands build on each other — `/productkit.problem` reads your `users.md`, `/productkit.solution` reads your problem and users, and `/productkit.spec` synthesizes everything into a single document. You can run `/productkit.clarify` and `/productkit.analyze` at any stage to check your work.
 
 ### 4. Review your artifacts
 
-After running the commands, your project root contains:
+After running the commands, your project contains:
 
 ```
 my-project/
@@ -77,9 +95,11 @@ my-project/
 ├── users.md               # User personas
 ├── problem.md             # Problem statement
 ├── assumptions.md         # Prioritized assumptions
+├── validation.md          # Validation results & scripts
 ├── solution.md            # Chosen solution
 ├── priorities.md          # Ranked feature list
 ├── spec.md                # Complete product spec
+├── audit.md               # Spec vs codebase audit (on demand)
 ├── .productkit/config.json
 ├── .claude/commands/      # Slash command prompts
 ├── CLAUDE.md
@@ -87,6 +107,8 @@ my-project/
 └── .gitignore
 ```
 
+If you used `--artifact-dir docs/product`, artifacts live in `docs/product/` instead of the project root.
+
 These markdown files are your product foundation — share them with your team, commit them to git, or hand `spec.md` to engineering.
 
 ## CLI Commands
@@ -95,13 +117,30 @@ These markdown files are your product foundation — share them with your team,
 |---------|-------------|
 | `productkit init <name>` | Scaffold a new project |
 | `productkit init --existing` | Add Product Kit to the current directory |
+| `productkit init --minimal` | Skip constitution, start with users/problem |
+| `productkit init --artifact-dir <dir>` | Store artifacts in a custom directory |
 | `productkit status` | Show progress — which artifacts exist and what's next |
+| `productkit export` | Export all artifacts as a single combined markdown file |
+| `productkit export --output <file>` | Export to a custom filename |
+| `productkit diff` | Show what changed in artifacts since last commit |
+| `productkit diff --staged` | Show staged artifact changes |
+| `productkit doctor` | Check project health (missing files, outdated commands) |
 | `productkit update` | Refresh slash commands to the latest version |
 | `productkit reset` | Remove all artifacts and start over |
 | `productkit list` | Show available slash commands with descriptions |
 | `productkit completion` | Output shell completion script (bash/zsh) |
 | `productkit check` | Verify Claude Code is installed |
 
+## Cowork Plugin (No CLI Required)
+
+If you prefer Claude Cowork over the command line, Product Kit is also available as a Cowork plugin. Same guided workflows, no terminal needed.
+
+1. Download [`product-kit-plugin.zip`](https://github.com/iamquechua/product-kit/releases/download/latest-plugin/product-kit-plugin.zip) from [GitHub Releases](https://github.com/iamquechua/product-kit/releases/tag/latest-plugin)
+2. In Cowork, go to **Plugins → + → Upload plugin**
+3. Select the zip file
+
+Once installed, type `/product-kit:users`, `/product-kit:problem`, etc. in Cowork's chat. See [plugin/README.md](plugin/README.md) for details.
+
 ## How It Works
 
 Product Kit is a thin scaffolding tool. The real work happens in slash commands — markdown prompt files that live in `.claude/commands/`. When you type `/productkit.users` in Claude Code, it reads the prompt file and starts a guided conversation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "productkit",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Slash-command-driven product thinking toolkit for Claude Code",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -9,18 +9,23 @@ const updateCommand = require('./commands/update');
 const resetCommand = require('./commands/reset');
 const listCommand = require('./commands/list');
 const completionCommand = require('./commands/completion');
+const exportCommand = require('./commands/export');
+const diffCommand = require('./commands/diff');
+const doctorCommand = require('./commands/doctor');
 
 const program = new Command();
 
 program
   .name('productkit')
   .description(chalk.cyan.bold('Product thinking toolkit for Claude Code'))
-  .version('1.7.0');
+  .version('1.9.0');
 
 program
   .command('init [projectName]')
   .description('Initialize a new product research project')
   .option('--existing', 'Add Product Kit to the current directory')
+  .option('--minimal', 'Skip constitution, start with users/problem')
+  .option('--artifact-dir <dir>', 'Directory for artifacts (default: project root)')
   .action(initCommand);
 
 program
@@ -55,6 +60,23 @@ program
   .option('--shell <shell>', 'Shell type (bash or zsh)')
   .action(completionCommand);
 
+program
+  .command('export')
+  .description('Export all artifacts as a single combined markdown file')
+  .option('--output <file>', 'Output filename', 'export.md')
+  .action(exportCommand);
+
+program
+  .command('diff')
+  .description('Show what changed since last commit across artifacts')
+  .option('--staged', 'Show staged changes instead of unstaged')
+  .action(diffCommand);
+
+program
+  .command('doctor')
+  .description('Check project health (missing files, outdated commands, etc.)')
+  .action(doctorCommand);
+
 program.parse(process.argv);
 
 if (process.argv.length === 2) {

package/src/commands/diff.js

@@ -0,0 +1,69 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+const { getArtifactDir } = require('../utils/fileUtils');
+
+const ARTIFACT_FILES = [
+  'constitution.md',
+  'users.md',
+  'problem.md',
+  'assumptions.md',
+  'validation.md',
+  'solution.md',
+  'priorities.md',
+  'spec.md',
+];
+
+async function diff(options) {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  // Check if git is available
+  try {
+    execSync('git rev-parse --git-dir', { cwd: root, stdio: 'ignore' });
+  } catch {
+    console.error(chalk.red('Not a git repository. The diff command requires git.'));
+    process.exit(1);
+  }
+
+  const artifactDir = getArtifactDir(root);
+  const relDir = path.relative(root, artifactDir);
+  const existing = ARTIFACT_FILES
+    .map(f => relDir && relDir !== '.' ? path.join(relDir, f) : f)
+    .filter(f => fs.existsSync(path.join(root, f)));
+
+  if (existing.length === 0) {
+    console.error(chalk.red('No artifacts found. Run some slash commands first.'));
+    process.exit(1);
+  }
+
+  const gitArgs = options.staged ? ['diff', '--cached'] : ['diff'];
+  const cmd = ['git', ...gitArgs, '--', ...existing].join(' ');
+
+  let output;
+  try {
+    output = execSync(cmd, { cwd: root, encoding: 'utf-8' });
+  } catch (err) {
+    // git diff returns exit code 1 when there are differences in some configs
+    output = err.stdout || '';
+  }
+
+  if (!output) {
+    console.log(chalk.yellow('No changes to artifacts since last commit.'));
+    if (!options.staged) {
+      console.log(chalk.dim('Tip: use --staged to see staged changes.'));
+    }
+    return;
+  }
+
+  console.log(output);
+}
+
+module.exports = diff;

package/src/commands/doctor.js

@@ -0,0 +1,115 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+async function doctor() {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  const results = { pass: 0, warn: 0, fail: 0 };
+
+  function pass(msg) { results.pass++; console.log(chalk.green(`  pass  ${msg}`)); }
+  function warn(msg) { results.warn++; console.log(chalk.yellow(`  warn  ${msg}`)); }
+  function fail(msg) { results.fail++; console.log(chalk.red(`  fail  ${msg}`)); }
+
+  console.log();
+  console.log(chalk.bold('Project health check'));
+  console.log();
+
+  // 1. Config file
+  try {
+    const config = fs.readJsonSync(configPath);
+    if (config.version) {
+      pass('Config file is valid');
+    } else {
+      warn('Config file missing version field');
+    }
+  } catch {
+    fail('Config file is not valid JSON');
+  }
+
+  // 2. Commands directory
+  const commandsDir = path.join(root, '.claude', 'commands');
+  if (fs.existsSync(commandsDir)) {
+    pass('Commands directory exists');
+  } else {
+    fail('Commands directory missing (.claude/commands/)');
+  }
+
+  // 3. Check for expected command templates
+  const templatesDir = path.join(__dirname, '..', '..', 'templates', 'commands');
+  const expectedCommands = fs.readdirSync(templatesDir);
+
+  // Account for minimal mode
+  let config = {};
+  try { config = fs.readJsonSync(configPath); } catch {}
+  const skippable = config.minimal ? ['productkit.constitution.md'] : [];
+
+  const missing = [];
+  for (const cmd of expectedCommands) {
+    if (skippable.includes(cmd)) continue;
+    if (!fs.existsSync(path.join(commandsDir, cmd))) {
+      missing.push(cmd);
+    }
+  }
+
+  if (missing.length === 0) {
+    pass('All expected command templates present');
+  } else {
+    for (const m of missing) {
+      fail(`Missing command template: ${m}`);
+    }
+  }
+
+  // 4. Check for outdated commands
+  const outdated = [];
+  for (const cmd of expectedCommands) {
+    if (skippable.includes(cmd)) continue;
+    const installedPath = path.join(commandsDir, cmd);
+    if (!fs.existsSync(installedPath)) continue;
+
+    const installed = fs.readFileSync(installedPath, 'utf-8');
+    const bundled = fs.readFileSync(path.join(templatesDir, cmd), 'utf-8');
+    if (installed !== bundled) {
+      outdated.push(cmd);
+    }
+  }
+
+  if (outdated.length === 0) {
+    pass('All command templates up to date');
+  } else {
+    for (const o of outdated) {
+      warn(`Outdated command: ${o} — run productkit update`);
+    }
+  }
+
+  // 5. Git initialized
+  try {
+    execSync('git rev-parse --git-dir', { cwd: root, stdio: 'ignore' });
+    pass('Git repository initialized');
+  } catch {
+    warn('No git repository — consider running git init');
+  }
+
+  // Summary
+  console.log();
+  const parts = [];
+  if (results.pass > 0) parts.push(chalk.green(`${results.pass} passed`));
+  if (results.warn > 0) parts.push(chalk.yellow(`${results.warn} warning(s)`));
+  if (results.fail > 0) parts.push(chalk.red(`${results.fail} failed`));
+  console.log(chalk.bold('Result: ') + parts.join(', '));
+  console.log();
+
+  if (results.fail > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = doctor;

package/src/commands/export.js

@@ -0,0 +1,51 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { getArtifactDir } = require('../utils/fileUtils');
+
+const ARTIFACTS = [
+  { file: 'constitution.md', label: 'Constitution' },
+  { file: 'users.md', label: 'Users' },
+  { file: 'problem.md', label: 'Problem' },
+  { file: 'assumptions.md', label: 'Assumptions' },
+  { file: 'validation.md', label: 'Validation' },
+  { file: 'solution.md', label: 'Solution' },
+  { file: 'priorities.md', label: 'Priorities' },
+  { file: 'spec.md', label: 'Spec' },
+];
+
+async function exportCommand(options) {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  const artifactDir = getArtifactDir(root);
+  const existing = ARTIFACTS.filter(a => fs.existsSync(path.join(artifactDir, a.file)));
+
+  if (existing.length === 0) {
+    console.error(chalk.red('No artifacts found. Run some slash commands first.'));
+    process.exit(1);
+  }
+
+  const sections = [];
+  for (const artifact of existing) {
+    const content = fs.readFileSync(path.join(artifactDir, artifact.file), 'utf-8');
+    sections.push(content);
+  }
+
+  const projectName = path.basename(root);
+  const header = `# ${projectName} — Product Kit Export\n\n_Exported: ${new Date().toISOString().split('T')[0]}_\n\n---\n`;
+  const combined = header + sections.join('\n\n---\n\n') + '\n';
+
+  const outputFile = options.output || 'export.md';
+  fs.writeFileSync(path.join(root, outputFile), combined);
+
+  console.log(chalk.green.bold(`Exported ${existing.length} artifact(s) to ${outputFile}`));
+}
+
+module.exports = exportCommand;

package/src/commands/init.js

@@ -2,7 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 
-function scaffold(projectRoot, projectName) {
+function scaffold(projectRoot, projectName, minimal, artifactDir) {
   const templatesDir = path.join(__dirname, '..', '..', 'templates');
 
   // Create directories
@@ -10,15 +10,24 @@ function scaffold(projectRoot, projectName) {
   fs.ensureDirSync(path.join(projectRoot, '.claude', 'commands'));
 
   // Write config
-  fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), {
+  const config = {
     version: '1.0.0',
     created: new Date().toISOString(),
-  }, { spaces: 2 });
+  };
+  if (minimal) {
+    config.minimal = true;
+  }
+  if (artifactDir) {
+    config.artifact_dir = artifactDir;
+    fs.ensureDirSync(path.join(projectRoot, artifactDir));
+  }
+  fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), config, { spaces: 2 });
 
   // Copy slash command templates
   const commandsDir = path.join(templatesDir, 'commands');
   const commandFiles = fs.readdirSync(commandsDir);
   for (const file of commandFiles) {
+    if (minimal && file === 'productkit.constitution.md') continue;
     fs.copyFileSync(
       path.join(commandsDir, file),
       path.join(projectRoot, '.claude', 'commands', file)
@@ -61,13 +70,13 @@ async function init(projectName, options) {
     }
 
     try {
-      scaffold(projectRoot, path.basename(projectRoot));
+      scaffold(projectRoot, path.basename(projectRoot), options.minimal, options.artifactDir);
 
       console.log(chalk.green.bold('Product Kit added to existing project!'));
       console.log();
       console.log(chalk.cyan('Next steps:'));
       console.log('  1. claude');
-      console.log('  2. /productkit.constitution');
+      console.log(`  2. /productkit.${options.minimal ? 'users' : 'constitution'}`);
       console.log();
     } catch (error) {
       console.error(chalk.red('Error initializing:'), error.message);
@@ -89,7 +98,7 @@ async function init(projectName, options) {
   }
 
   try {
-    scaffold(projectRoot, projectName);
+    scaffold(projectRoot, projectName, options.minimal, options.artifactDir);
 
     // Init git repo
     const { execSync } = require('child_process');
@@ -104,7 +113,7 @@ async function init(projectName, options) {
     console.log(chalk.cyan('Next steps:'));
     console.log(`  1. cd ${projectName}`);
     console.log('  2. claude');
-    console.log('  3. /productkit.constitution');
+    console.log(`  3. /productkit.${options.minimal ? 'users' : 'constitution'}`);
     console.log();
   } catch (error) {
     console.error(chalk.red('Error initializing project:'), error.message);

package/src/commands/reset.js

@@ -2,12 +2,14 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const readline = require('readline');
+const { getArtifactDir } = require('../utils/fileUtils');
 
 const ARTIFACTS = [
   'constitution.md',
   'users.md',
   'problem.md',
   'assumptions.md',
+  'validation.md',
   'solution.md',
   'priorities.md',
   'spec.md',
@@ -36,9 +38,11 @@ async function reset(options) {
     process.exit(1);
   }
 
+  const artifactDir = getArtifactDir(root);
+
   // Find existing artifacts
   const existing = ARTIFACTS.filter(file =>
-    fs.existsSync(path.join(root, file))
+    fs.existsSync(path.join(artifactDir, file))
   );
 
   if (existing.length === 0) {
@@ -67,7 +71,7 @@ async function reset(options) {
   }
 
   for (const file of existing) {
-    fs.removeSync(path.join(root, file));
+    fs.removeSync(path.join(artifactDir, file));
     console.log(chalk.yellow(`  removed ${file}`));
   }
 

package/src/commands/status.js

@@ -1,12 +1,14 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const { getArtifactDir } = require('../utils/fileUtils');
 
 const ARTIFACTS = [
   { file: 'constitution.md', command: '/productkit.constitution', label: 'Constitution' },
   { file: 'users.md', command: '/productkit.users', label: 'Users' },
   { file: 'problem.md', command: '/productkit.problem', label: 'Problem' },
   { file: 'assumptions.md', command: '/productkit.assumptions', label: 'Assumptions' },
+  { file: 'validation.md', command: '/productkit.validate', label: 'Validation' },
   { file: 'solution.md', command: '/productkit.solution', label: 'Solution' },
   { file: 'priorities.md', command: '/productkit.prioritize', label: 'Priorities' },
   { file: 'spec.md', command: '/productkit.spec', label: 'Spec' },
@@ -22,11 +24,12 @@ async function status() {
     process.exit(1);
   }
 
+  const artifactDir = getArtifactDir(root);
   const done = [];
   const remaining = [];
 
   for (const artifact of ARTIFACTS) {
-    const exists = fs.existsSync(path.join(root, artifact.file));
+    const exists = fs.existsSync(path.join(artifactDir, artifact.file));
     if (exists) {
       done.push(artifact);
     } else {

package/src/utils/fileUtils.js

@@ -12,7 +12,19 @@ function getProjectRoot() {
   return null;
 }
 
+function getArtifactDir(root) {
+  const configPath = path.join(root, '.productkit', 'config.json');
+  try {
+    const config = fs.readJsonSync(configPath);
+    if (config.artifact_dir) {
+      return path.join(root, config.artifact_dir);
+    }
+  } catch {}
+  return root;
+}
+
 module.exports = {
   isProductKitProject,
   getProjectRoot,
+  getArtifactDir,
 };

package/templates/CLAUDE.md

@@ -10,19 +10,23 @@ Use these commands in order to build your product foundation:
 2. `/productkit.users` — Define target user personas
 3. `/productkit.problem` — Frame the problem statement
 4. `/productkit.assumptions` — Extract and prioritize assumptions
-5. `/productkit.solution` — Brainstorm and evaluate solutions
-6. `/productkit.prioritize` — Score and rank features
-7. `/productkit.spec` — Generate a product spec
-8. `/productkit.clarify` — Resolve ambiguities across artifacts
-9. `/productkit.analyze` — Run a completeness/consistency check
+5. `/productkit.validate` — Validate assumptions with interview scripts and surveys
+6. `/productkit.solution` — Brainstorm and evaluate solutions
+7. `/productkit.prioritize` — Score and rank features
+8. `/productkit.spec` — Generate a product spec
+9. `/productkit.clarify` — Resolve ambiguities across artifacts
+10. `/productkit.analyze` — Run a completeness/consistency check
+11. `/productkit.bootstrap` — Auto-draft all artifacts from an existing codebase
+12. `/productkit.audit` — Compare spec against codebase and surface gaps
 
 ## Artifacts
 
-Product artifacts are written to the project root as markdown files:
+Product artifacts are written as markdown files. Check `.productkit/config.json` for an `artifact_dir` field — if set, artifacts live in that directory instead of the project root. Default artifact locations:
 - `constitution.md` — Product principles and values
 - `users.md` — Target user personas
 - `problem.md` — Problem statement
 - `assumptions.md` — Prioritized assumptions
+- `validation.md` — Assumption validation results, interview scripts, and survey questions
 - `solution.md` — Chosen solution with alternatives considered
 - `priorities.md` — Scored and ranked feature list
 - `spec.md` — Complete product spec ready for engineering
@@ -30,3 +34,5 @@ Product artifacts are written to the project root as markdown files:
 ## Workflow
 
 Start with `/productkit.constitution` or `/productkit.users`, then work through the commands in order. Each command reads previous artifacts to maintain consistency.
+
+For existing projects, use `/productkit.bootstrap` to auto-draft all artifacts from your codebase in one session.

package/templates/README.md

@@ -1,6 +1,6 @@
 # {{PROJECT_NAME}}
 
-A product research project powered by [Product Kit](https://github.com/douno/product-kit).
+A product research project powered by [Product Kit](https://github.com/iamquechua/product-kit). See the [full guide](https://iamquechua.github.io/product-kit/) for a walkthrough.
 
 ## Getting Started
 
@@ -14,20 +14,26 @@ Then use the slash commands to build your product foundation:
 2. `/productkit.users` — Define target user personas
 3. `/productkit.problem` — Frame the problem statement
 4. `/productkit.assumptions` — Extract and prioritize assumptions
-5. `/productkit.solution` — Brainstorm and evaluate solutions
-6. `/productkit.prioritize` — Score and rank features
-7. `/productkit.spec` — Generate a product spec
-8. `/productkit.clarify` — Resolve ambiguities
-9. `/productkit.analyze` — Check consistency and completeness
+5. `/productkit.validate` — Validate assumptions with interviews and surveys
+6. `/productkit.solution` — Brainstorm and evaluate solutions
+7. `/productkit.prioritize` — Score and rank features
+8. `/productkit.spec` — Generate a product spec
+9. `/productkit.clarify` — Resolve ambiguities
+10. `/productkit.analyze` — Check consistency and completeness
+11. `/productkit.bootstrap` — Auto-draft all artifacts from existing codebase
+12. `/productkit.audit` — Compare spec against actual implementation
 
 ## Artifacts
 
+Artifacts are written to the project root by default. If `artifact_dir` is set in `.productkit/config.json`, they are written there instead.
+
 | File | Description |
 |------|-------------|
 | `constitution.md` | Product principles and values |
 | `users.md` | Target user personas |
 | `problem.md` | Problem statement |
 | `assumptions.md` | Prioritized assumptions |
+| `validation.md` | Assumption validation, interview scripts, survey questions |
 | `solution.md` | Chosen solution with alternatives considered |
 | `priorities.md` | Scored and ranked feature list |
 | `spec.md` | Complete product spec ready for engineering |

package/templates/commands/productkit.analyze.md

@@ -10,7 +10,9 @@ Evaluate the overall quality, consistency, and completeness of the product think
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read artifacts there instead of the project root. If not set, default to the project root.
+
+Read all existing artifacts:
 - `constitution.md`
 - `users.md`
 - `problem.md`

package/templates/commands/productkit.assumptions.md

@@ -41,7 +41,9 @@ Also read if they exist:
 
 ## Output
 
-Write to `assumptions.md` in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write to `assumptions.md`:
 
 ```markdown
 # Assumptions

package/templates/commands/productkit.audit.md

@@ -0,0 +1,140 @@
+---
+description: Compare your spec against the actual codebase and surface gaps
+---
+
+You are a product audit specialist comparing what was planned (in the product artifacts) against what was actually built (in the codebase). Your job is to surface gaps, scope creep, and unmet acceptance criteria so the PM can make informed decisions about what to do next.
+
+## Your Role
+
+Read the product spec and supporting artifacts, then systematically scan the codebase to determine what was implemented, what's missing, what was added beyond the spec, and whether acceptance criteria are met. Produce a clear, actionable audit report.
+
+## Before You Start
+
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read artifacts there instead of the project root. If not set, default to the project root.
+
+Read these artifacts (required):
+- `spec.md` — the product spec (required)
+- `priorities.md` — feature priorities and v1 scope (required)
+
+Also read if they exist:
+- `solution.md` — chosen solution
+- `validation.md` — assumption validation results
+- `assumptions.md` — known risks
+
+At minimum, `spec.md` must exist. If it's missing, tell the user to run `/productkit.spec` first.
+
+### Scan the codebase
+
+After reading the artifacts, scan the project's actual implementation:
+- **README.md** — project description, setup instructions, documented features
+- **package.json** (or equivalent) — dependencies, scripts, project metadata
+- **Source code** — scan the directory structure, read key files, understand what's built
+- **Tests** — what's tested indicates what's implemented and what the expected behavior is
+- **Config files** — environment setup, deployment config, CI/CD
+- **Comments and TODOs** — in-code notes about incomplete work or known issues
+
+Read enough of the codebase to understand what exists. You don't need to read every file — focus on entry points, key modules, and test files to build a picture of what's implemented.
+
+## Process
+
+1. **Map spec features to code** — For each feature in `spec.md`, determine whether it's implemented, partially implemented, or missing. Reference specific files/modules as evidence.
+
+2. **Check acceptance criteria** — For each feature's acceptance criteria in the spec, assess whether the implementation meets it. Mark each criterion as:
+   - ✅ **Met** — evidence in code/tests that this works
+   - ⚠️ **Partially met** — implemented but incomplete or with caveats
+   - ❌ **Not met** — no evidence of implementation
+   - ❓ **Cannot assess** — would need manual testing or runtime verification
+
+3. **Identify scope creep** — Look for significant functionality in the codebase that isn't described in the spec. Flag it — it may be intentional evolution or unplanned drift.
+
+4. **Check deferred items** — Review the "Out of Scope" and "Deferred to v2+" sections. Were any deferred items actually built? Were any v1 items actually deferred?
+
+5. **Review risks and assumptions** — If `validation.md` exists, check whether invalidated assumptions affected the implementation. If `assumptions.md` exists, check whether high-risk assumptions have been addressed in the code (error handling, fallbacks, etc.).
+
+6. **Check success metrics** — Are the success metrics from the spec measurable with the current implementation? Is there analytics, logging, or monitoring in place?
+
+7. **Present findings** — Walk the PM through the audit, feature by feature. Discuss implications and recommendations.
+
+## Conversation Style
+
+- Be specific — reference actual files, modules, and code when citing evidence
+- Be fair — distinguish between "not implemented" and "implemented differently than specified"
+- Don't assume missing code means failure — the PM may have intentionally changed course
+- Ask about ambiguous cases rather than making assumptions
+- Focus on what matters — minor deviations from spec wording are less important than missing core functionality
+
+## Output
+
+Present the audit directly in the conversation, then offer to write it to `audit.md`. Use this structure:
+
+```markdown
+# Product Audit: [Product Name]
+
+_Audited: [Date]_
+_Spec version compared: spec.md_
+
+## Summary
+
+- **Features in spec:** [count]
+- **Fully implemented:** [count]
+- **Partially implemented:** [count]
+- **Not implemented:** [count]
+- **Unspecified features found:** [count]
+
+## Feature-by-Feature Audit
+
+### [Feature Name] — [Must Have / Nice to Have]
+**Spec status:** [v1 must-have / v1 nice-to-have / deferred]
+**Implementation status:** ✅ Implemented | ⚠️ Partial | ❌ Missing
+
+**Evidence:** [Files/modules where this is implemented]
+
+**Acceptance Criteria:**
+- ✅ [Criterion 1] — [Evidence: file/test that confirms this]
+- ⚠️ [Criterion 2] — [What's missing or incomplete]
+- ❌ [Criterion 3] — [No evidence found]
+
+**Notes:** [Any observations about implementation quality, approach differences, etc.]
+
+### [Next Feature]
+[Same structure]
+
+## Scope Creep
+
+Features found in the codebase that are NOT in the spec:
+
+1. **[Feature/functionality]** — Found in [file/module]. [Is this intentional? Should it be added to the spec?]
+
+## Deferred Items Check
+
+| Deferred Item | Was it built? | Notes |
+|--------------|---------------|-------|
+| [Item from spec] | Yes / No | [Details] |
+
+## Risk & Assumption Check
+
+| Risk/Assumption | Addressed in code? | How |
+|----------------|-------------------|-----|
+| [From spec/validation.md] | Yes / No / Partial | [Evidence] |
+
+## Success Metrics Readiness
+
+| Metric | Measurable? | How |
+|--------|------------|-----|
+| [From spec] | Yes / No | [What's in place — analytics, logging, etc.] |
+
+## Recommendations
+
+### Critical (block launch)
+1. [Missing must-have feature or unmet critical criterion]
+
+### Important (address soon)
+1. [Partially implemented feature that needs completion]
+
+### Nice to Have (backlog)
+1. [Minor gaps or improvements]
+
+### Process Observations
+- [Any patterns noticed — e.g., "spec was too vague on X, leading to implementation ambiguity"]
+- [Suggestions for improving the spec → build → audit cycle]
+```

package/templates/commands/productkit.bootstrap.md

@@ -0,0 +1,81 @@
+---
+description: Auto-draft all product artifacts from an existing codebase
+---
+
+You are a product analyst bootstrapping Product Kit artifacts for an existing project. Your job is to read the codebase and draft each artifact so the user gets a fast start instead of building from scratch.
+
+## Your Role
+
+Analyze the existing project — code, docs, README, config files, comments — and draft product artifacts in workflow order. Present each draft for user approval before writing it.
+
+## Before You Start
+
+1. Read the project's README, CLAUDE.md, package.json (or equivalent), and scan the directory structure to understand what this project does.
+2. Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
+3. Check which artifacts already exist (constitution.md, users.md, problem.md, assumptions.md, solution.md, priorities.md, spec.md) in the artifact directory. **Skip any that already exist** — tell the user you're skipping them.
+4. Check `.productkit/config.json` — if `minimal: true`, skip `constitution.md`.
+
+## Process
+
+Work through each missing artifact in this order:
+
+### 1. Constitution (`constitution.md`)
+Draft based on: README vision/mission, CLAUDE.md principles, project conventions.
+- Product vision — infer from what the project does
+- Core principles — infer from code patterns, docs, and design choices
+- Non-negotiables — infer from what the project explicitly avoids
+
+### 2. Users (`users.md`)
+Draft based on: README audience, docs, issue tracker themes, CLI help text, UI copy.
+- Identify 2-4 user types from project context
+- Describe each with specifics inferred from the codebase
+
+### 3. Problem (`problem.md`)
+Draft based on: README "why", issue patterns, gaps the project fills.
+- Frame the core problem the project solves
+- Ground it in the users you just defined
+
+### 4. Assumptions (`assumptions.md`)
+Draft based on: implicit bets in the architecture, undocumented dependencies, target audience guesses.
+- Surface 5-10 assumptions from code and docs
+- Categorize by risk (high/medium/low)
+
+### 5. Solution (`solution.md`)
+Draft based on: the actual implementation, architecture choices, alternatives mentioned in docs/comments.
+- Describe the chosen approach and why
+- Note alternatives that were likely considered
+
+### 6. Priorities (`priorities.md`)
+Draft based on: feature completeness, TODO comments, open issues, roadmap docs.
+- List features/capabilities by apparent priority
+- Flag gaps between what exists and what's needed
+
+### 7. Spec (`spec.md`)
+Draft based on: all previous artifacts plus technical implementation details.
+- Synthesize everything into a product spec
+
+## For Each Artifact
+
+1. **Show your draft** — present the full markdown content
+2. **Explain your reasoning** — briefly note what codebase signals you used
+3. **Ask for approval** — "Should I write this to `[filename]`? Or would you like to adjust anything?"
+4. **On approval** — write the file to the artifact directory
+5. **On feedback** — revise and re-present
+
+## Conversation Style
+
+- Be direct — present drafts quickly, don't over-ask before showing something
+- Flag low-confidence sections with "[Needs input]" where the codebase doesn't give enough signal
+- If the codebase has very little documentation, acknowledge gaps honestly and ask the user to fill in
+- After each artifact, move to the next without prompting — keep momentum
+
+## Output
+
+Each artifact follows the same format as its corresponding slash command would produce. Refer to the individual command templates for the expected structure.
+
+## When Done
+
+After all artifacts are written (or skipped), summarize:
+- Which artifacts were drafted and written
+- Which were skipped (already existed)
+- Suggest running `/productkit.clarify` to resolve any cross-artifact inconsistencies

package/templates/commands/productkit.clarify.md

@@ -10,7 +10,9 @@ Cross-reference all existing artifacts, find inconsistencies, and guide the user
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
+
+Read all existing artifacts:
 - `constitution.md`
 - `users.md`
 - `problem.md`

package/templates/commands/productkit.constitution.md

@@ -25,7 +25,9 @@ Act as a seasoned PM mentor. Guide the user through defining their product's cor
 
 ## Output
 
-Write the final constitution to `constitution.md` in the project root with this format:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write the final constitution to `constitution.md` with this format:
 
 ```markdown
 # Product Constitution

package/templates/commands/productkit.prioritize.md

@@ -27,11 +27,12 @@ If `solution.md` does not exist, tell the user to run `/productkit.solution` fir
 2. **Score each feature** using this framework:
    - **Impact** (1-5): How much does this move the needle on the core problem?
    - **Confidence** (1-5): How sure are we that users need this? (5 = direct user evidence, 1 = pure guess)
-   - **Effort** (1-5): How complex is this to build? (1 = trivial, 5 = massive)
+   - **Effort** (1-5): How complex is this to build? (1 = trivial, 5 = massive). **This is a PM estimate — mark as `Eng. Validated: No`.**
    - **Priority Score** = (Impact × Confidence) / Effort
 3. **Discuss the ranking** — Present the scored list. Ask the user if the ranking feels right. Adjust if needed.
 4. **Draw the v1 line** — Which features make the cut for the first release? Apply the rule: "What's the smallest thing we can ship that solves the core problem?"
 5. **Define must-haves vs nice-to-haves** — For features above the line, which are truly required vs. which could be cut if time runs short?
+6. **Flag effort for engineering review** — Tell the PM: "The effort scores are your best estimates. Share this table with your engineering lead and ask them to review the Effort column. When they've provided their input, update the Effort scores and set `Eng. Validated` to `Yes`, then run `/productkit.prioritize` again to recalculate rankings."
 
 ## Conversation Style
 
@@ -42,7 +43,9 @@ If `solution.md` does not exist, tell the user to run `/productkit.solution` fir
 
 ## Output
 
-Write to `priorities.md` in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write to `priorities.md`:
 
 ```markdown
 # Feature Priorities
@@ -52,12 +55,15 @@ Priority Score = (Impact × Confidence) / Effort
 
 ## Feature Rankings
 
-| Rank | Feature | Impact | Confidence | Effort | Score | Status |
-|------|---------|--------|------------|--------|-------|--------|
-| 1 | [Feature] | 5 | 4 | 2 | 10.0 | v1 must-have |
-| 2 | [Feature] | 4 | 4 | 2 | 8.0 | v1 must-have |
-| 3 | [Feature] | 4 | 3 | 3 | 4.0 | v1 nice-to-have |
-| 4 | [Feature] | 3 | 2 | 4 | 1.5 | v2 |
+| Rank | Feature | Impact | Confidence | Effort | Eng. Validated | Score | Status |
+|------|---------|--------|------------|--------|----------------|-------|--------|
+| 1 | [Feature] | 5 | 4 | 2 | No | 10.0 | v1 must-have |
+| 2 | [Feature] | 4 | 4 | 2 | No | 8.0 | v1 must-have |
+| 3 | [Feature] | 4 | 3 | 3 | No | 4.0 | v1 nice-to-have |
+| 4 | [Feature] | 3 | 2 | 4 | No | 1.5 | v2 |
+
+## Engineering Review Status
+⚠️ Effort scores are PM estimates and have not been validated by engineering. Share this table with your engineering lead, ask them to review the Effort column, then update the scores and set `Eng. Validated` to `Yes`. Run `/productkit.prioritize` again to recalculate rankings.
 
 ## v1 Scope
 ### Must-Haves
@@ -73,3 +79,16 @@ Priority Score = (Impact × Confidence) / Effort
 - [Decision 1 and rationale]
 - [Decision 2 and rationale]
 ```
+
+### When the PM returns with engineering-validated effort scores
+
+When the user runs `/productkit.prioritize` again after updating effort scores:
+
+1. Read the existing `priorities.md`
+2. Check the `Eng. Validated` column. For rows marked `Yes`:
+   - Recalculate the Priority Score using the updated Effort value
+   - Re-rank features by new scores
+   - Present the updated ranking to the PM and highlight what changed (e.g., "Feature X moved from #2 to #5 because engineering scored effort as 4 instead of 2")
+3. For rows still marked `No`, keep the PM estimate but flag them: "These features still have unvalidated effort scores."
+4. Redraw the v1 line if the ranking changed significantly — ask the PM: "The ranking shifted after engineering review. Does the v1 scope still make sense, or should we adjust?"
+5. Update the Engineering Review Status section. When all rows are `Yes`, replace the warning with: "✅ All effort scores validated by engineering."

package/templates/commands/productkit.problem.md

@@ -34,7 +34,9 @@ If `users.md` does not exist, tell the user to run `/productkit.users` first.
 
 ## Output
 
-Write the problem statement to `problem.md` in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write the problem statement to `problem.md`:
 
 ```markdown
 # Problem Statement

package/templates/commands/productkit.solution.md

@@ -10,16 +10,34 @@ Guide the user from problem understanding to concrete solution ideas. Ensure eve
 
 ## Before You Start
 
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
+
 Read these files first (required):
 - `users.md` — who has this problem
 - `problem.md` — what problem we're solving
+- `validation.md` — assumption validation results (required)
 
 Also read if they exist:
 - `constitution.md` — product principles (use to filter solutions)
-- `assumptions.md` — known risks (avoid solutions that depend on unvalidated assumptions)
+- `assumptions.md` — known risks
 
 If `users.md` or `problem.md` do not exist, tell the user to run `/productkit.users` and `/productkit.problem` first.
 
+If `validation.md` does not exist, tell the user to run `/productkit.validate` first.
+
+### Validation Gate
+
+After reading `validation.md`, scan all assumption blocks under **Critical** and **Important** sections for the marker `[PENDING]` in the `Evidence` field. This is a mechanical check — look for the literal text `[PENDING]`.
+
+**If any Critical or Important assumption has `Evidence: [PENDING]`:**
+
+1. **Do not proceed with solution brainstorming.**
+2. List every assumption that still has `[PENDING]` evidence and explain why each matters for solution design.
+3. Tell the user: "These assumptions have no evidence yet. Run `/productkit.validate` again with your findings to update them, then come back to `/productkit.solution`."
+4. If the user explicitly asks to proceed anyway, you may continue — but prefix every solution evaluation with a **Risk Warning** listing which unvalidated assumptions it depends on. Make it clear the output is a hypothesis, not a validated plan.
+
+**Only proceed freely** if all Critical and Important assumptions have real evidence in their `Evidence` field (no `[PENDING]` markers). Low Risk assumptions with `[PENDING]` are acceptable and should not block.
+
 ## Process
 
 1. **Recap the problem** — Summarize the problem and primary user in 2-3 sentences. Confirm with the user.
@@ -44,7 +62,9 @@ If `users.md` or `problem.md` do not exist, tell the user to run `/productkit.us
 
 ## Output
 
-Write to `solution.md` in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write to `solution.md`:
 
 ```markdown
 # Solution

package/templates/commands/productkit.spec.md

@@ -10,7 +10,9 @@ Pull together everything the user has built — constitution, users, problem, as
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
+
+Read all existing artifacts:
 - `constitution.md` — product principles
 - `users.md` — target users (required)
 - `problem.md` — problem statement (required)
@@ -20,6 +22,17 @@ Read all existing artifacts in the project root:
 
 At minimum, `users.md`, `problem.md`, and `solution.md` must exist. If any are missing, tell the user which commands to run first.
 
+### Engineering Effort Review Check
+
+If `priorities.md` exists, scan the feature table for the `Eng. Validated` column. If any v1 must-have or nice-to-have features have `Eng. Validated: No`:
+
+1. **Do not proceed with the spec.**
+2. List the features with unvalidated effort scores.
+3. Tell the PM: "Your effort scores haven't been reviewed by engineering yet. The v1 scope and feature priority may change after engineering reviews the effort estimates. Share `priorities.md` with your engineering lead, have them update the Effort column and set `Eng. Validated` to `Yes`, then run `/productkit.prioritize` again to recalculate rankings. Once that's done, come back to `/productkit.spec`."
+4. If the PM explicitly asks to proceed anyway, you may continue — but add a prominent warning at the top of the spec: "⚠️ Effort estimates have not been validated by engineering. Feature scope and priority order may change." Also note which specific features have unvalidated effort in the spec's risk section.
+
+If all v1 features have `Eng. Validated: Yes`, proceed without warnings.
+
 ## Process
 
 1. **Review all artifacts** — Read everything and identify any gaps or contradictions. Flag these before proceeding.
@@ -37,7 +50,7 @@ At minimum, `users.md`, `problem.md`, and `solution.md` must exist. If any are m
 
 ## Output
 
-Write to `spec.md` in the project root:
+Write to `spec.md`:
 
 ```markdown
 # Product Spec: [Product Name]

package/templates/commands/productkit.users.md

@@ -33,7 +33,9 @@ Read `constitution.md` if it exists — use the product vision to inform user di
 
 ## Output
 
-Write the final personas to `users.md` in the project root with this format:
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Write the final personas to `users.md` with this format:
 
 ```markdown
 # Target Users

package/templates/commands/productkit.validate.md

@@ -0,0 +1,192 @@
+---
+description: Validate assumptions with interview scripts and survey questions
+---
+
+You are a research methodologist and validation specialist helping PMs test their assumptions before committing to a solution.
+
+## Your Role
+
+Turn prioritized assumptions into actionable validation materials — interview scripts and survey questions. If the PM already has evidence, capture it. If not, give them the tools to go get it.
+
+## Before You Start
+
+Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
+
+Read existing artifacts:
+- `assumptions.md` — prioritized assumptions (required)
+- `users.md` — user personas (optional, used for interview targeting)
+- `problem.md` — problem statement (optional, for context)
+
+At minimum, `assumptions.md` must exist. If it's missing, tell the user to run `/productkit.assumptions` first.
+
+### Check for raw validation data
+
+Look for a `validation-data/` directory in the artifact directory (or project root if no artifact_dir is set). If it exists, read the files inside:
+
+- **`interviews.csv`** — interview responses. Columns: Participant, Question, Response, Notes.
+- **`survey-responses.csv`** — survey results. Columns are the survey questions generated on the first run.
+- **`desk-research.csv`** — desk research findings. Columns: Assumption, Source, Finding, URL, Date.
+- **`.md` or `.txt` files** — free-form interview transcripts or notes. Read each one.
+- **Any other files** — note their presence but flag that you can only analyze text-based formats.
+
+If `validation-data/` contains filled-in files, these are the **primary source of evidence**. Analyze them directly rather than relying on the PM's summary. If the directory doesn't exist or is empty, proceed with the normal flow (ask the PM for evidence or generate validation materials).
+
+**Privacy note:** Interview data may contain personally identifiable information. Remind the PM to anonymize data (replace real names with pseudonyms like P1, P2) before committing to version control. Suggest adding `validation-data/` to `.gitignore` if the data is sensitive.
+
+## Process
+
+1. **Review assumptions** — Read `assumptions.md` and list the Critical and Important assumptions. Present them to the user.
+2. **Triage each assumption** — For each high-risk assumption, ask: "Do you already have evidence for or against this?" If yes, capture it and assess whether it validates, partially validates, or invalidates the assumption. If no, flag it for validation.
+3. **Generate interview script** — For assumptions that need qualitative validation, write an interview script targeting the relevant user persona from `users.md`. Group questions by assumption. Include warm-up and closing sections.
+4. **Generate survey questions** — For assumptions that can be tested quantitatively, write survey questions in formats ready for Typeform/Google Forms (Likert scale, multiple choice, open text). Tag each question with the assumption it tests.
+5. **Generate data collection templates** — Create the `validation-data/` directory and write CSV templates:
+   - **`validation-data/interviews.csv`** — Pre-filled with the interview questions from the script. Columns: `Participant`, `Question`, `Response`, `Notes`. Each row has a question pre-populated; the PM fills in responses for each participant.
+   - **`validation-data/survey-responses.csv`** — Columns are the survey questions generated in step 4. Each row will be one respondent's answers. First row is headers only — the PM pastes in exported survey data or fills in manually.
+   - **`validation-data/desk-research.csv`** — Pre-filled with one row per assumption that needs desk research. Columns: `Assumption`, `Source`, `Finding`, `URL`, `Date`. The PM fills in what they find.
+6. **Summarize status** — Present a clear picture: what's validated, what's invalidated, what still needs fieldwork.
+7. **Finalize** — Write the validation artifact and data collection templates after user approval. Tell the PM: "Fill in the CSV files in `validation-data/` as you collect data, then run `/productkit.validate` again for me to analyze your findings."
+
+## Conversation Style
+
+- Be rigorous — "I think users want this" is not evidence. Push for specifics.
+- Accept diverse evidence — user interviews, analytics data, support tickets, competitor research, domain expertise all count
+- For invalidated assumptions, flag the downstream impact ("This assumption is in your problem statement — you may need to revisit it")
+- Keep interview questions open-ended and non-leading
+- Keep survey questions clear and unambiguous — no double-barreled questions
+- If all critical assumptions are already validated, celebrate that and generate materials only for remaining gaps
+
+## Output
+
+Write to `validation.md`. Every assumption gets a structured block with an `Evidence` field. For assumptions the PM has already validated, fill in the evidence. For assumptions that still need validation, write `[PENDING]` as the evidence value. This marker is critical — `/productkit.solution` will check for `[PENDING]` markers and block if any exist on critical or important assumptions.
+
+```markdown
+# Validation
+
+## Assumptions
+
+### Critical
+
+1. **[Assumption]**
+   - Priority: Critical
+   - Source: [assumptions.md reference]
+   - Method: [Interview | Survey | Desk research | Domain expertise]
+   - Evidence: [Specific findings — quotes, data, sources] OR [PENDING]
+   - Status: Validated | Partially validated | Invalidated | Needs validation
+
+2. **[Assumption]**
+   - Priority: Critical
+   - Source: [assumptions.md reference]
+   - Method: [Method used or suggested]
+   - Evidence: [Specific findings] OR [PENDING]
+   - Status: Validated | Partially validated | Invalidated | Needs validation
+
+### Important
+
+1. **[Assumption]**
+   - Priority: Important
+   - Source: [assumptions.md reference]
+   - Method: [Method used or suggested]
+   - Evidence: [Specific findings] OR [PENDING]
+   - Status: Validated | Partially validated | Invalidated | Needs validation
+
+### Low Risk
+
+1. **[Assumption]**
+   - Priority: Low
+   - Source: [assumptions.md reference]
+   - Evidence: [Specific findings] OR [PENDING]
+   - Status: Validated | Needs validation
+
+## Interview Script
+
+### Target: [User persona from users.md]
+**Context:** [Brief description of what you're validating]
+
+**Warm-up (2-3 min)**
+- [Opening question to build rapport]
+- [Question about their current workflow/situation]
+
+**Core Questions (15-20 min)**
+1. [Question targeting assumption X]
+   - _Follow-up if yes:_ [Probe deeper]
+   - _Follow-up if no:_ [Explore why]
+2. [Question targeting assumption Y]
+   - _Follow-up:_ [Probe deeper]
+
+**Closing (2-3 min)**
+- Is there anything about [topic] that I didn't ask about but should have?
+- Do you know anyone else who deals with [problem] that I could talk to?
+
+## Survey Questions
+
+Ready to paste into Typeform / Google Forms:
+
+1. [Question] — Multiple choice: [Option A / Option B / Option C / Other]
+   - _Tests assumption:_ [Which one]
+2. [Question] — Scale: 1 (Strongly disagree) to 5 (Strongly agree)
+   - _Tests assumption:_ [Which one]
+3. [Question] — Open text
+   - _Tests assumption:_ [Which one]
+
+## Next Steps
+- [What to do with validation results before moving to /productkit.solution]
+```
+
+### Important: How evidence gets entered and reviewed
+
+There are two ways evidence enters the system. Raw data files are preferred; manual entry is the fallback.
+
+**Path A: Raw data files (preferred)**
+
+The PM drops raw data into `validation-data/`:
+- Interview transcripts/notes → `.md` or `.txt` files
+- Survey exports → `.csv` files
+- Desk research findings → `.md` files with sources
+
+Then runs `/productkit.validate`. Claude reads the raw files, extracts evidence relevant to each assumption, and updates `validation.md` directly. The PM does not need to fill in evidence manually — Claude does the analysis.
+
+**Path B: Manual entry (fallback)**
+
+For evidence that doesn't have a raw file (e.g., a phone call, in-person observation, domain expertise), the PM fills in the `Evidence:` fields directly in `validation.md`, replacing `[PENDING]` with their findings. Then runs `/productkit.validate` for review.
+
+---
+
+**Review mode — when `validation.md` already exists:**
+
+1. Read the existing `validation.md`
+2. **Check `validation-data/` for raw files.** If files are present:
+   - Read each file and identify which assumptions it provides evidence for
+   - For interview transcripts: extract relevant quotes, count participants, note patterns across interviews
+   - For survey CSVs: calculate response counts, percentages, distributions for relevant questions. For large files (100+ rows), summarize key statistics rather than reading every row.
+   - For desk research: extract cited sources, statistics, and findings
+   - Cross-reference findings against each `[PENDING]` assumption
+   - Write the extracted evidence into the `Evidence:` field, citing the source file (e.g., "From interview-03.md: '...'", "Survey data (n=45): 72% responded...")
+   - Present your analysis to the PM for confirmation before finalizing
+3. **For manually entered evidence** (no raw file), review the quality:
+   - **Is it specific?** — "Users liked it" is not evidence. Push back: "How many users? What exactly did they say?"
+   - **Does it include the method?** — Interview, survey, desk research, analytics? If not stated, ask.
+   - **Does it include the source/sample?** — How many people? Which report? What dataset? If missing, ask.
+   - **Does it actually test the assumption?** — Evidence about user demographics doesn't validate a usability assumption. Flag mismatches.
+4. For evidence that passes review (from raw data or manual entry):
+   - Update the `Status:` field to Validated / Partially validated / Invalidated
+   - For invalidated assumptions, add `- Impact:` noting what needs to change in previous artifacts
+5. For manually entered evidence that is too weak or vague:
+   - **Do not update the Status.** Keep it as `Needs validation`.
+   - Reset `Evidence:` back to `[PENDING]`
+   - Explain what's missing and what good evidence would look like for this specific assumption
+6. Keep the interview script and survey sections — they may still be useful for remaining `[PENDING]` items
+7. When all critical and important assumptions have evidence that passed review (no `[PENDING]` markers), tell the user they're clear to run `/productkit.solution`
+
+**Evidence quality bar by method:**
+
+| Method | Minimum evidence required |
+|--------|--------------------------|
+| Interview | Number of participants, at least one direct quote or specific observation per assumption |
+| Survey | Sample size, response rate, key percentages or distributions |
+| Desk research | Source name, publication date, specific statistic or finding cited |
+| Analytics | Metric name, time period, actual numbers |
+| Domain expertise | Specific experience cited (role, years, context), not just "I believe" |
+
+**Note on `validation-data/` and privacy:**
+- Remind the PM to anonymize interview transcripts (replace real names with pseudonyms) before committing to git
+- Suggest adding `validation-data/` to `.gitignore` if the data contains sensitive or personally identifiable information