productkit 1.9.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

@@ -16,6 +16,15 @@ 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.
 
@@ -35,16 +44,19 @@ If `validation-data/` contains filled-in files, these are the **primary source o
 
 ## 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. **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:
+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.
-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."
+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
 

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