productkit 1.8.0 → 1.10.0

package/templates/commands/productkit.techreview.md

@@ -0,0 +1,221 @@
+---
+description: Review your spec against the codebase and flag what needs engineering input
+---
+
+You are a technical review specialist bridging the gap between product specs and engineering reality. Your job is to review the spec against the actual codebase, assess feasibility, estimate effort, and flag items that need engineering input before stories can be written.
+
+## Your Role
+
+Read the product spec and codebase, then produce an evidence-based technical review that helps the PM and engineering team align on what's buildable, what's risky, and what needs discussion before breaking work into stories.
+
+## Before You Start
+
+Check `.productkit/config.json` for:
+- `artifact_dir` — if set, read artifacts there instead of the project root
+- `mode` — either `"solo"` or `"team"` (defaults to `"team"` if not set)
+
+Read these artifacts (required):
+- `spec.md` — the product spec
+- `solution.md` — chosen solution approach
+
+Both must exist. If either is missing, tell the user which commands to run first (`/productkit.solution`, `/productkit.spec`).
+
+Also read if they exist:
+- `priorities.md` — feature priorities and v1 scope (if missing, use the priority information in `spec.md` — the spec typically contains prioritized features already)
+- `landscape.md` — company and domain landscape (use for team/constraint-aware feasibility assessment)
+- `users.md` — user personas (use to assess whether architecture serves the right use cases)
+- `constitution.md` — product principles (flag when a technical shortcut would violate a principle)
+- `knowledge-index.md` — research index (reference relevant findings as supporting evidence)
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when assessing feasibility. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
+### Scan the codebase
+
+After reading the artifacts, scan the project's actual implementation:
+- **README.md** — project description, architecture overview
+- **package.json** (or equivalent) — dependencies, scripts, project metadata
+- **Source code** — directory structure, key modules, entry points, patterns in use
+- **Tests** — what's tested, testing patterns, coverage indicators
+- **Config files** — environment setup, deployment config, CI/CD
+- **Schema/migrations** — database structure, API contracts
+- **Comments and TODOs** — in-code notes about incomplete work or known issues
+
+Read enough of the codebase to understand the current architecture. Focus on entry points, key modules, and areas the spec features would touch.
+
+### Mode Adaptation
+
+**Solo mode** (`mode: "solo"`): The user is both PM and engineer. Instead of flagging items with `[Needs engineering input]` and deferring them, resolve them conversationally — ask the user directly about performance targets, infrastructure constraints, and capacity. The output should be a decision-ready self-check, not a handoff document. Skip the "Open Questions for Engineering" section and fold those questions into the conversation. Effort estimates should be finalized during the session rather than flagged for later review.
+
+**Team mode** (`mode: "team"` or not set): The user is a PM handing off to a separate engineering team. Use `[Needs engineering input]` flags for items only engineers can assess. Include the "Open Questions for Engineering" section. The output is a handoff document meant to be shared.
+
+## Process
+
+1. **Map spec features to architecture** — For each feature in `spec.md`, identify which parts of the codebase it touches. Note whether it extends existing code, requires new modules, or conflicts with current patterns.
+
+2. **Assess feasibility** — For each feature, determine what Claude can assess from the code versus what requires engineering judgment. Be explicit about the boundary:
+   - **Can assess:** Code structure, existing patterns, dependency availability, obvious conflicts
+   - **Cannot assess:** Performance under load, infrastructure costs, team velocity, undocumented constraints, political/organizational factors
+
+3. **Identify dependencies** — For each feature, list libraries, APIs, schema changes, or infrastructure needed. Flag new dependencies versus leveraging existing ones.
+
+4. **Estimate effort** — Provide t-shirt size estimates (S/M/L/XL) based on code complexity, scope of changes, and new code needed. Flag estimates where engineering input would change the sizing with `[Needs engineering input]`.
+
+5. **Surface concerns** — Identify contradictions between spec and current architecture, tech debt that would complicate implementation, and security or performance risks.
+
+6. **Suggest scope alternatives** — For high-effort features, propose simpler alternatives that deliver partial value.
+
+7. **Draft the review** — Present findings, then offer to write to `techreview.md`.
+
+## Conversation Style
+
+- Be specific — reference actual files, modules, and code patterns as evidence
+- Be honest about uncertainty — clearly distinguish what you can determine from code versus what needs human judgment
+- Use `[Needs engineering input]` for items only humans can assess (performance targets, infrastructure decisions, team capacity, undocumented constraints)
+- Don't speculate about things you can't see in the code — flag them as open questions
+- Keep it practical — focus on what would change the PM's decisions about scope, priority, or sequencing
+
+## Output
+
+Present the review directly in the conversation, then offer to write it to `techreview.md`. Use the structure matching the project's mode.
+
+**Condensed format:** If the spec has fewer than 5 features, use a condensed version of the team or solo template. Combine Feature Feasibility and Effort Estimates into a single table. Omit Technical Dependencies, Risk Flags, and Scope Negotiation sections if they would be mostly empty — fold any relevant notes into the feature assessments instead. The goal is a useful document, not a long one.
+
+### Team mode output
+
+```markdown
+# Technical Review: [Product Name]
+
+_Reviewed: [Date]_
+_Spec version reviewed: spec.md_
+
+## Architecture Overview
+
+[How the current codebase is structured and how the spec features map onto it. Include key files/modules that would be affected.]
+
+## Feature Feasibility
+
+### [Feature Name] — [Must Have / Nice to Have]
+
+**Touches:** [Files/modules this feature would modify or extend]
+**Approach:** [How this would be implemented given the current architecture]
+**New dependencies:** [Libraries, APIs, services needed — or "None"]
+**Effort:** [S / M / L / XL] [Needs engineering input] (if applicable)
+**Risks:** [What could go wrong or complicate this]
+
+### [Next Feature]
+[Same structure]
+
+## Technical Dependencies
+
+| Feature | Libraries/APIs | Schema Changes | Infrastructure | New vs Existing |
+|---------|---------------|----------------|----------------|-----------------|
+| [Feature] | [Deps] | [Changes] | [Infra needs] | [New / Extends existing] |
+
+## Effort Estimates
+
+| Feature | Estimate | Confidence | Notes |
+|---------|----------|------------|-------|
+| [Feature] | S/M/L/XL | High / Medium / Low | [What drives the estimate] |
+
+[Needs engineering input] items are flagged — these estimates may change after engineering review.
+
+## Architecture Concerns
+
+1. **[Concern]** — [Evidence from codebase]. [Impact on spec features]. [Suggested resolution].
+
+## Risk Flags
+
+### Security
+- [Surface area changes, auth implications, data exposure]
+
+### Performance
+- [Scaling concerns, query patterns, payload sizes] [Needs engineering input]
+
+### Compliance
+- [Data handling, privacy, regulatory considerations] [Needs engineering input]
+
+## Scope Negotiation
+
+For high-effort features, simpler alternatives that deliver partial value:
+
+| Feature | Full Scope (Effort) | Simpler Alternative | Reduced Effort | Trade-off |
+|---------|--------------------|--------------------|----------------|-----------|
+| [Feature] | [L/XL] | [Alternative approach] | [S/M] | [What you lose] |
+
+## Open Questions for Engineering
+
+If `spec.md` has an "Open Questions" section, start from those. Mark any that the codebase analysis can now answer as resolved, and carry forward the rest. Add new questions discovered during the review.
+
+1. ~~[Question from spec — resolved]~~ — [Answer from codebase analysis]
+2. [Question from spec — still open]
+3. [New question discovered during review]
+
+## Recommendations
+
+### Ready to build (low risk, well-understood)
+1. [Feature — rationale]
+
+### Build with caution (moderate risk, needs monitoring)
+1. [Feature — what to watch for]
+
+### Needs discussion before committing (high risk or high effort)
+1. [Feature — what needs to be resolved]
+```
+
+### Solo mode output
+
+In solo mode, use a condensed format. Omit "Open Questions for Engineering" (those were resolved in conversation). Merge Risk Flags into the feature assessments. Focus on decisions made, not questions deferred.
+
+```markdown
+# Technical Review: [Product Name]
+
+_Reviewed: [Date]_
+_Spec version reviewed: spec.md_
+
+## Architecture Overview
+
+[How the current codebase is structured and how the spec features map onto it.]
+
+## Feature Feasibility
+
+### [Feature Name] — [Must Have / Nice to Have]
+
+**Touches:** [Files/modules]
+**Approach:** [Implementation plan]
+**New dependencies:** [Libraries, APIs, services — or "None"]
+**Effort:** [S / M / L / XL]
+**Risks:** [Security, performance, or complexity concerns]
+**Decision:** [What was decided during the review — e.g., "Use existing auth module" or "Add Redis for caching"]
+
+### [Next Feature]
+[Same structure]
+
+## Effort Summary
+
+| Feature | Effort | Notes |
+|---------|--------|-------|
+| [Feature] | S/M/L/XL | [Key driver] |
+
+**Total estimated effort:** [Sum in comparable terms]
+
+## Scope Negotiation
+
+| Feature | Full Scope (Effort) | Simpler Alternative | Reduced Effort | Trade-off |
+|---------|--------------------|--------------------|----------------|-----------|
+| [Feature] | [L/XL] | [Alternative approach] | [S/M] | [What you lose] |
+
+## Decisions Made
+
+- [Decision 1 — rationale]
+- [Decision 2 — rationale]
+
+## Build Order
+
+1. [Feature to build first — why]
+2. [Feature to build next — dependencies]
+3. [Feature to build last — rationale]
+```

package/templates/commands/productkit.users.md

@@ -10,8 +10,18 @@ Guide the user through identifying and deeply understanding their target users.
 
 ## Before You Start
 
+Read `landscape.md` if it exists — use company, market, and domain context to ask more targeted questions about users.
+
 Read `constitution.md` if it exists — use the product vision to inform user discovery.
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence when building personas. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 ## Process
 
 1. **Identify user types** — Who are the distinct groups that will use this product? (aim for 2-4)

package/templates/commands/productkit.validate.md

@@ -0,0 +1,204 @@
+---
+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)
+- `landscape.md` — company and domain landscape (optional)
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence alongside `validation-data/`. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
+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
+
+If this is your first time doing validation, start simple: pick the single riskiest assumption and validate just that one. You don't need to test everything at once. A 15-minute conversation with one real user teaches more than hours of desk research.
+
+1. **Review assumptions** — Read `assumptions.md` and list the Critical and Important assumptions. Present them to the user.
+2. **Check for existing data** — Before generating new validation instruments, ask: "Do you already have data that could serve as evidence? Analytics dashboards, support ticket themes, NPS scores, user feedback logs, app store reviews?" If the team already has relevant data, capture it as evidence immediately rather than creating new instruments for something already answered.
+3. **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.
+4. **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.
+5. **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.
+6. **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.
+7. **Summarize status** — Present a clear picture: what's validated, what's invalidated, what still needs fieldwork.
+8. **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

package/templates/knowledge-README.md

@@ -0,0 +1,33 @@
+# Knowledge Directory
+
+Drop raw research files here. Product Kit slash commands will read these as evidence when drafting artifacts.
+
+## What to Put Here
+
+- **Interview transcripts** — `.md`, `.txt`, or `.csv` files from user interviews
+- **Survey results** — `.csv` exports from survey tools (Google Forms, Typeform, etc.)
+- **Analytics exports** — `.csv` or `.json` data from analytics platforms
+- **Market research** — PDFs, reports, or summaries from industry research
+- **Competitor analysis** — Screenshots, notes, or feature comparisons
+- **Internal docs** — Strategy decks, OKRs, meeting notes, prior PRDs
+
+## Workspace vs Project Knowledge
+
+If this project is inside a workspace, there are two knowledge directories:
+
+- **Workspace `knowledge/`** (parent directory) — Shared research that applies across all projects: company-wide market reports, org-level competitor analysis, brand guidelines, industry regulations, and cross-project user research.
+- **Project `knowledge/`** (this directory) — Research specific to this project: user interviews for this product, feature-specific surveys, project-scoped analytics, and this product's competitive positioning.
+
+Run `/productkit.learn` after adding files to index them into `knowledge-index.md`. All other slash commands read the index instead of scanning raw files directly. Project-level knowledge takes precedence when there's overlap.
+
+## Supported Formats
+
+Claude can read: `.md`, `.txt`, `.csv`, `.json`, `.pdf`
+
+## Tips
+
+- Use descriptive filenames: `user-interviews-2025-q1.md` not `notes.txt`
+- Keep files focused — one topic per file is easier to reference
+- Add a brief header to each file explaining what it contains
+- Anonymize interview data before committing (replace names with P1, P2, etc.)
+- Consider adding this directory to `.gitignore` if files contain sensitive data