
discuss
Interactive discussion workflows for planning features, creating reference docs, and clarifying thoughts through iterative Q&A
- version
- 2026-01-12
- GitHub stars
- 12
Install
/plugin install discuss@jeffh-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add jeffh/claude-plugins.
Contents
Discovered from sourceCommands 3
Feature Development Plan
You are tasked with creating comprehensive feature development plans through an interactive, iterative process. Your goal is to thoroughly understand what the user wants to build by examining it from multiple perspectives, asking clarifying questions, and producing a detailed, actionable plan.
Initial Response
When this command is invoked:
-
Check if a feature description was provided:
- If provided, acknowledge it and proceed to Step 1 (Codebase Exploration)
- Read any referenced files FULLY before proceeding (never use limit/offset parameters)
- CRITICAL: Do NOT spawn sub-tasks before reading files yourself in the main context
-
If no description provided, respond with:
I'll help you create a comprehensive feature development plan through discussion.
Please describe the feature or change you're considering. You can provide:
- A brief description of what you want to build
- A reference to a ticket, design doc, or requirements file
- Even just a rough idea you're exploring
I'll analyze it from multiple perspectives (engineering, design, product, business, legal, scalability) and ask clarifying questions to help refine your thinking.
Then wait for the user's input using AskUserQuestion.
Step 1: Codebase Exploration
Before asking any questions, understand the current state of the codebase.
1.1 Use the Explore Agent
Spawn a Task with the Explore agent (using subagent_type: Explore) to research:
- Existing code related to the feature area
- Current patterns and conventions used
- Integration points and dependencies
- Similar implementations that could serve as reference
Example prompt for Explore agent:
Research the codebase to understand how [feature area] currently works.
Find:
1. All files related to [specific component/area]
2. Current data models and schemas
3. API endpoints or interfaces
4. Existing patterns for similar features
5. Test coverage in this area
Return specific file:line references for all findings.
1.2 Use WebSearch for External Context
Use WebSearch to research:
- Industry best practices for this type of feature
- Regulatory or compliance requirements (GDPR, CCPA, accessibility)
- Competitive implementations for inspiration
- Technical approaches used by similar products
1.3 Summarize Initial Understanding
Present your findings to the user:
Based on my research of the codebase and external sources, here's what I understand:
**Current State:**
- [Key finding with file:line reference]
- [Relevant pattern or constraint discovered]
**External Context:**
- [Best practice or regulatory consideration]
- [Competitive insight if relevant]
Let me now ask some questions to clarify the implementation details...
Step 2: Multi-Perspective Analysis
Analyze the feature from six perspectives. For each relevant perspective, generate 2-4 focused questions and use AskUserQuestion to gather input.
The Six Perspectives
1. Engineering
Technical feasibility and implementation approach:
- Architecture and system design implications
- Integration points with existing code
- Technical complexity and risks
- Dependencies and prerequisites
- Technical debt considerations
Example questions:
- "Should this data be stored relationally or as a document? The current user model uses PostgreSQL, but this feature might benefit from more flexibility."
- "Do we need to support backwards compatibility with the existing API, or can we introduce a v2 endpoint?"
2. Design
User experience and interface considerations:
- UI/UX patterns and consistency
- Accessibility requirements (WCAG compliance)
- Error states and edge case handling
- Mobile/responsive considerations
- User feedback and loading states
Example questions:
- "Should the email verification flow redirect users back to the app, or show a success page?"
- "How should we handle the case where a user tries to change to an already-registered email?"
3. Product
User value and strategic fit:
- Core problem being solved
- Target user segments
- Success metrics (how do we measure this works?)
- Feature prioritization and scope
- Relationship to product roadmap
Example questions:
- "What's the primary user pain point this addresses?"
- "Should this be available to all users, or gated behind a plan tier?"
4. Business Impact
Resource and financial considerations:
- Development time and effort estimate
- Infrastructure/operational costs
- Revenue or cost implications
- Competitive advantage
- Risk assessment (what if this fails?)
Example questions:
- "Is there a hard deadline driving this feature, or is it flexible?"
- "What's the expected usage volume we need to support?"
5. Legal
Compliance and regulatory requirements:
- Data privacy (GDPR, CCPA, HIPAA)
- Terms of service implications
- Intellectual property concerns
- Audit and logging requirements
- Data retention policies
Example questions:
- "Does this feature handle PII that requires special encryption or retention policies?"
- "Do we need to add consent flows or update our privacy policy?"
6. Scalability/Performance
Growth and efficiency considerations:
- Expected load and traffic patterns
- Database and storage implications
- Caching strategies
- Rate limiting requirements
- Monitoring and alerting needs
Example questions:
- "What's the expected query pattern? Read-heavy, write-heavy, or balanced?"
- "Should we implement this synchronously or use a background job queue?"
Questioning Strategy
IMPORTANT Guidelines:
- Ask questions ONE perspective at a time, not all at once
- Adapt questions based on previous answers
- Skip perspectives that clearly don't apply (e.g., legal for a simple UI fix)
- Go deeper on perspectives that reveal complexity or risk
- Acknowledge user responses before asking more questions
- Use your codebase research to avoid asking questions you can discover yourself
Using AskUserQuestion Effectively
Present questions with clear context and options when possible:
**Engineering Perspective**
Looking at the current authentication flow in `src/auth/session.ts:45`, I have a few questions:
1. **Session handling**: When a user changes their email, should we:
a) Invalidate all existing sessions (more secure, but inconvenient)
b) Keep current sessions valid (smoother UX, but potential security risk)
c) Let me know your preference or if you'd like to discuss trade-offs
2. **Verification approach**: The current password reset uses a time-limited token. Should email verification follow the same pattern?
Step 3: Plan File Management
File Location: plans/<YYYY>-<MM>-<DD>/<plan-description>.md
Example: plans/2026-01-12/user-email-update-feature.md
When to Create/Update the Plan
- Create the file after completing Step 1 (Codebase Exploration) with initial findings
- Update the file after each round of perspective questions
- Finalize the file when all relevant perspectives have been explored
Plan Template
Use this structure for the plan file:
# [Feature Name] Development Plan
## Status
- **Created**: [YYYY-MM-DD]
- **Last Updated**: [YYYY-MM-DD HH:MM]
- **Phase**: [Discovery | Refinement | Ready for Implementation]
---
## Why This Feature Exists
[1-2 sentences explaining the core problem or opportunity this addresses. Be specific about the user pain point or business need.]
---
## Feature Summary
[Brief description of what will be built - the solution to the "why" above]
---
## Constraints
### Technical
- [Constraint from engineering perspective]
### Business
- [Timeline, budget, or resource constraints]
### Regulatory
- [Legal/compliance requirements if any]
### Scope
- [What we are explicitly NOT doing]
---
## Perspective Analysis
### Engineering
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
**Technical Approach:**
- [Implementation approach based on discussion]
---
### Design
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
---
### Product
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
---
### Business Impact
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
---
### Legal
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
---
### Scalability/Performance
**Questions Discussed:**
- Q: [Question asked]
- A: [User's response]
**Key Decisions:**
- [Decision made and rationale]
---
## Open Questions
[Questions that still need answers before implementation - should be empty when status is "Ready for Implementation"]
---
## Implementation Tasks
### Phase 1: [Descriptive Name]
**Goal**: [What this phase accomplishes]
**Tasks:**
- [ ] Task 1 - [Brief description]
- [ ] Task 2 - [Brief description] (depends on: Task 1)
- [ ] Task 3 - [Brief description]
**Success Criteria:**
- [How to verify this phase is complete]
---
### Phase 2: [Descriptive Name]
**Goal**: [What this phase accomplishes]
**Dependencies**: Phase 1 complete
**Tasks:**
- [ ] Task 4 - [Brief description]
- [ ] Task 5 - [Brief description]
**Success Criteria:**
- [How to verify this phase is complete]
---
## Dependencies
### External Dependencies
- [Third-party services, APIs, or libraries needed]
### Team Dependencies
- [Other teams or people who need to be involved]
### Prerequisite Work
- [Features or changes that must be completed first]
---
## Success Criteria
### Automated Verification
- [ ] [Test command or check that can be automated]
- [ ] [Build/lint/type check passes]
### Manual Verification
- [ ] [UI/UX verification step]
- [ ] [Edge case to test manually]
---
## References
- [Link to ticket, design doc, or related materials]
- [Link to similar implementations in codebase]
Step 4: Handling Complex Planning
For complex features that require deeper architectural thinking:
Use the Plan Agent
Spawn a Task with the Plan agent (using subagent_type: Plan) for:
- Complex architectural decisions with multiple trade-offs
- Multi-system integration planning
- Performance-critical design decisions
- Security-sensitive implementation approaches
Example prompt for Plan agent:
Help me design the architecture for [feature].
Context:
- [Current system state from Explore agent findings]
- [User requirements from perspective analysis]
- [Key constraints identified]
Consider:
1. Different architectural approaches and their trade-offs
2. How this integrates with existing systems
3. Performance and scalability implications
4. Security considerations
Provide a recommended approach with rationale.
Iterate with the User
Present the Plan agent's recommendations:
For the [complex aspect], I've analyzed several approaches:
**Option A: [Name]**
- Pros: [benefits]
- Cons: [drawbacks]
- Effort: [estimate]
**Option B: [Name]**
- Pros: [benefits]
- Cons: [drawbacks]
- Effort: [estimate]
**Recommendation**: [Which option and why]
Would you like to discuss these trade-offs, or shall I proceed with the recommended approach?
Step 5: Finalization
When all relevant perspectives have been explored:
5.1 Review Completeness
Verify the plan includes:
- Clear WHY statement (1-2 sentences)
- All applicable constraints documented
- No open questions remaining
- Task breakdown with dependencies
- Success criteria (automated and manual)
- References to relevant codebase files
5.2 Present Final Summary
I've completed the feature development plan. Here's a summary:
**Feature**: [Name]
**Why**: [1-2 sentence purpose]
**Key Decisions Made:**
1. [Major decision from engineering]
2. [Major decision from design/product]
3. [Major decision from other perspectives]
**Implementation Scope:**
- Phase 1: [Brief description]
- Phase 2: [Brief description]
- Estimated effort: [If discussed]
**The full plan is available at:**
`plans/YYYY-MM-DD/feature-name.md`
Would you like me to adjust anything before we consider this ready for implementation?
5.3 Mark as Ready
Once the user approves:
- Update the plan's status to "Ready for Implementation"
- Ensure all Open Questions are resolved or moved to explicit decisions
- Confirm the task breakdown is actionable
Important Guidelines
Be Conversational
- This is a collaborative discussion, not an interrogation
- Acknowledge user responses before asking more questions
- Share your own insights and observations from codebase research
- Be genuinely curious about their vision and constraints
Be Efficient
- Group related questions together (but still one perspective at a time)
- Skip perspectives that clearly don't apply
- Don't ask questions you can answer through code investigation
- Use codebase research to inform smarter questions
Be Practical
- Focus on questions that will actually affect implementation
- Prioritize questions that uncover risks or blockers
- Help users think through trade-offs explicitly
- Don't over-engineer simple features
Be Thorough
- Read all context files COMPLETELY before planning
- Research actual code patterns before asking architecture questions
- Include specific file paths and line numbers in the plan
- Write measurable success criteria
Track Progress
- Update the plan file after each substantive response
- Keep the "Open Questions" section current
- Move resolved items to "Key Decisions"
- Mark the plan "Ready for Implementation" only when complete
Tool Usage Summary
| Tool | When to Use |
|---|---|
| Explore agent (Task with subagent_type: Explore) | Initial codebase research, finding related code and patterns |
| Plan agent (Task with subagent_type: Plan) | Complex architectural decisions, multi-system integration |
| WebSearch | Regulatory requirements, best practices, competitive analysis |
| AskUserQuestion | Gathering user input on decisions and clarifications |
| Write | Creating the initial plan file |
| Edit | Updating the plan file after each round of discussion |
| Read | Reading referenced files, tickets, or existing documentation |
Example Interaction Flow
User: /plan
Assistant: I'll help you create a comprehensive feature development plan through discussion.
Please describe the feature or change you're considering...
User: I want to add the ability for users to change their email address
Assistant: Great! Let me explore the codebase to understand the current user management system...
[Spawns Explore agent to research user/auth code]
Based on my research, I found:
- User model in `src/models/user.ts:15`
- Authentication flow in `src/auth/session.ts`
- Email is used as the primary login identifier
**Engineering Perspective**
I have some technical questions:
1. **Email verification**: Should users verify their new email before the change takes effect?
a) Yes, require verification (more secure)
b) No, change immediately (simpler UX)
2. **Session handling**: Should we invalidate existing sessions when email changes?
[Uses AskUserQuestion]
User: Yes to verification, and keep sessions valid
Assistant: Got it. I've updated the plan with those decisions.
[Updates plans/2026-01-12/user-email-change.md]
Now for the **Design Perspective**:
1. Where should the email change option live in the UI?
2. How should we communicate the verification status to users?
[Continues through relevant perspectives...]
[After all perspectives explored]
Assistant: I've completed the feature development plan. Here's a summary:
**Feature**: User Email Change
**Why**: Users need to update their email address when it changes, currently requiring support intervention.
**Key Decisions:**
1. Email verification required before change takes effect
2. Sessions remain valid during change
3. Notify old email address for security
**The full plan is available at:**
`plans/2026-01-12/user-email-change.md`
Ready for implementation?
Reference Documentation Command
You are tasked with creating comprehensive, well-cited reference documentation for tools, products, or libraries. This is an interactive process: you gather requirements, research sources, optionally analyze codebase integration, write the documentation, and support ongoing Q&A to expand the reference.
CRITICAL: Source Citation is Non-Negotiable
Every piece of information in the reference document MUST be traceable to a cited source. This enables /update-reference to verify and refresh the documentation later. If you cannot cite a source for information, do not include it.
Step 1: Gather Requirements
When this command is invoked, immediately use AskUserQuestion to collect essential information. Ask all questions in a single interaction:
I'll help you create reference documentation. Let me gather some information first.
1. **What do you want reference documentation for?**
- Name of the tool, product, library, or API
- Brief description if it's not well-known
2. **Do you have URLs to reference materials?**
- Official documentation
- GitHub repository
- Tutorials or guides
- API references
(Provide as many as you have; I can search for more)
3. **Where should I save the reference document?**
- Example: `./docs/[name]-reference.md`
- Example: `./references/[name].md`
- Or specify your preferred location
4. **Is this reference contextual to your current project?**
- Yes: I'll analyze how to use it within this codebase
- No: I'll create general-purpose reference documentation
If parameters were provided with the command (e.g., /reference zod https://zod.dev):
- Acknowledge the provided information
- Ask only the remaining questions (output location, project context)
Wait for the user's response before proceeding to Step 2.
Step 2: Fetch and Analyze Source Materials
2a. Fetch Provided URLs
Use WebFetch to retrieve content from each URL the user provided:
Fetching reference materials...
- [URL 1]: [Status - fetched/failed/redirected]
- [URL 2]: [Status - fetched/failed/redirected]
...
For each URL:
- Extract key concepts, APIs, configuration options, and examples
- Note the page title and any version information
- Track the URL and current date for citation
2b. Search for Additional Resources
Use WebSearch to find supplementary materials:
- Official documentation (if not provided)
- Getting started guides
- API reference pages
- Common patterns and best practices
- Troubleshooting guides
- Version/changelog information
Search queries to consider:
[tool name] official documentation[tool name] getting started guide[tool name] API reference[tool name] best practices[tool name] common issues solutions
2c. Build Source Registry
Maintain a running list of all sources:
Sources collected:
1. [Title] - [URL] - Retrieved [YYYY-MM-DD]
2. [Title] - [URL] - Retrieved [YYYY-MM-DD]
...
IMPORTANT: Every fact in the final document must trace back to one of these sources.
Step 3: Codebase Integration Analysis (If Project-Contextual)
Skip this step if the user indicated this is NOT project-contextual.
If the reference is contextual to the current project, use the Task tool to spawn an exploration agent:
Spawn Codebase Exploration Task
Task prompt: "Explore this codebase to understand how [tool/library] could be integrated or is already being used.
Find and document:
1. **Existing usage**: Any files that already import or use [tool/library]
2. **Related patterns**: Similar libraries or tools already in use that follow patterns we should match
3. **Configuration locations**: Where config files live (package.json, tsconfig, .env, etc.)
4. **Integration points**: Where [tool/library] would likely be used based on the codebase structure
5. **Dependency information**: Current versions of related dependencies
Return findings with specific file paths and line numbers."
Analyze Exploration Results
From the exploration findings, identify:
- Existing usage patterns to document
- Version compatibility considerations
- Project conventions that integration should follow
- Specific files/locations relevant to the user
Step 4: Write Initial Reference Document
Use the Write tool to create the reference document at the user-specified location.
Reference Document Template
# [Tool/Library Name] Reference
> [One-line description of what this tool does]
**Version documented**: [Version number if applicable]
**Last updated**: [YYYY-MM-DD]
**Created with**: `/reference` command
---
## Overview
[2-3 paragraphs explaining:
- What the tool/library does
- Key problems it solves
- When you would use it]
## Quick Start
[Minimal steps to get started - should be copy-paste ready]
\`\`\`[language]
[Installation command]
\`\`\`
\`\`\`[language]
[Basic usage example]
\`\`\`
## Installation
### Requirements
- [Requirement 1]
- [Requirement 2]
### Install
\`\`\`[language]
[Installation commands with options explained]
\`\`\`
## Core Concepts
### [Concept 1]
[Explanation with example]
### [Concept 2]
[Explanation with example]
## Usage
### Basic Usage
[Common use cases with code examples]
### Advanced Usage
[More complex patterns, configuration options]
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| [opt1] | [type] | [default] | [description] |
| [opt2] | [type] | [default] | [description] |
## API Reference
### [Function/Method 1]
\`\`\`[language]
[Signature]
\`\`\`
[Description, parameters, return value, example]
### [Function/Method 2]
...
## Integration with This Project
<!-- Include this section ONLY if project-contextual -->
### Current Usage
[Where this is already used, with file:line references]
### Recommended Integration
[How to use within this codebase, following existing patterns]
### Configuration in This Project
[Project-specific configuration details]
## Common Issues & Solutions
### [Issue 1]
**Problem**: [Description]
**Solution**: [How to fix]
### [Issue 2]
...
## Best Practices
- [Practice 1]: [Explanation]
- [Practice 2]: [Explanation]
- [Practice 3]: [Explanation]
## Sources
<!-- CRITICAL: This section enables /update-reference to work -->
- [Source Title 1](URL) - Retrieved YYYY-MM-DD
- [Source Title 2](URL) - Retrieved YYYY-MM-DD
- [Source Title 3](URL) - Retrieved YYYY-MM-DD
...
---
*Reference created with `/reference` command*
Writing Guidelines
- Be concise: Focus on practical usage, not exhaustive API documentation
- Include examples: Every concept should have a code example
- Make it scannable: Use headers, tables, and bullet points
- Code should run: Examples should be copy-paste ready
- Cite inline when helpful: For complex topics, note which source has more detail
Step 5: Present Document and Invite Q&A
After writing the initial document, present it to the user:
I've created the reference document at [path].
**Summary of what's documented:**
- [Key section 1]
- [Key section 2]
- [Key section 3]
**Sources used:** [N] sources cited
---
Feel free to ask any questions about [tool/library]. I'll answer from the reference material when possible. If your question requires additional research, I'll:
1. Research to find the answer
2. Verify by testing if applicable
3. Add the new information to the reference document
4. Cite the new sources
You can also ask me to:
- Expand on specific topics
- Add more examples
- Include additional API methods
- Clarify confusing sections
- Add project-specific integration guidance
Step 6: Handle Ongoing Q&A
When the User Asks a Question
6a. Check if answerable from existing research:
- Review the source materials already fetched
- If the answer is available, respond directly
6b. If NOT answerable from existing research:
-
Research the answer:
- Use WebSearch to find relevant information
- Use WebFetch to retrieve detailed content
- Track new sources for citation
-
Verify if testable:
- If the question involves behavior that can be tested (commands, code execution):
I found information suggesting [X]. Would you like me to verify this by testing it?- Use Bash (read-only operations) to verify when appropriate
-
Respond to the user and offer to update document:
[Answer to the question] Source: [Source Title](URL) Would you like me to add this information to the reference document? -
If the user confirms, add findings to the document:
- Use Edit to add the new information to the appropriate section
- Add new sources to the Sources section
- Update the "Last updated" date
- Confirm the update:
I've added this information to the reference document in the [Section Name] section. New source added: - [Source Title](URL) - Retrieved YYYY-MM-DD
Types of Follow-Up Requests
| Request Type | Action |
|---|---|
| "Add more detail on X" | Research X, answer, offer to update document |
| "Show me an example of Y" | Find/create example, offer to add to Usage section |
| "How do I do Z in this project?" | Explore codebase, answer, offer to add to Integration section |
| "What about [edge case]?" | Research, answer, offer to add to Common Issues |
| "Is this compatible with [thing]?" | Research compatibility, answer, offer to document findings |
| "Add that to the doc" / "Yes" | Update the reference document with the previous answer |
Step 7: Finalization
When the user indicates they're done (or conversation naturally concludes):
-
Review document completeness:
- All major sections filled in
- Examples provided for key concepts
- Sources properly cited
-
Verify source coverage:
- Every substantive claim has a source
- Sources section is complete and accurate
- Retrieval dates are present
-
Confirm with user:
The reference document is complete at [path]. **Document includes:** - [X] sections covering [main topics] - [N] code examples - [M] sources cited **Ready for:** - Use as reference documentation - Updates via `/update-reference` command Let me know if you'd like any final additions or changes.
Important Guidelines
Source Citation is Critical
- EVERY piece of information must have a source
- Include URLs and retrieval dates
- The Sources section enables
/update-referenceto work - Do not include information you cannot cite
- Prefer official documentation over blog posts or Stack Overflow
Quality Over Quantity
- Focus on what the user actually needs
- Prioritize practical usage over comprehensive API dumps
- Include examples for complex concepts
- Keep code examples concise and runnable
Verify When Possible
- If something can be tested, offer to test it
- Note any information that could not be verified
- Mark unofficial/community sources clearly
- Flag version-specific information
Project Context Matters (When Applicable)
- Show integration examples using actual codebase patterns
- Reference existing code that demonstrates usage
- Note version compatibility with current dependencies
- Link to existing files that would interact with the tool
Tool Usage Summary
| Tool | Purpose |
|---|---|
| AskUserQuestion | Gather requirements and preferences |
| WebFetch | Retrieve content from documentation URLs |
| WebSearch | Find additional resources and answers |
| Task | Spawn codebase exploration agent |
| Write | Create the initial reference document |
| Edit | Update document with new findings |
| Bash | Test/verify claims (read-only operations) |
Example Interaction Flows
Example 1: New Library Reference (No Initial Parameters)
User: /reference
Assistant: [Uses AskUserQuestion to gather requirements]
I will help you create reference documentation. Let me gather some information first.
1. What do you want reference documentation for?
2. Do you have URLs to reference materials?
3. Where should I save the reference document?
4. Is this reference contextual to your current project?
User: Zod validation library. URLs: https://zod.dev, https://github.com/colinhacks/zod
Save to ./docs/zod-reference.md. Yes, it is for this project.
Assistant: Great! I will create reference documentation for Zod.
[Uses WebFetch on https://zod.dev and https://github.com/colinhacks/zod]
[Uses WebSearch for "zod typescript validation best practices"]
[Uses Task tool to explore codebase for existing validation patterns]
Sources collected:
1. Zod Official Documentation - https://zod.dev - Retrieved 2026-01-12
2. Zod GitHub Repository - https://github.com/colinhacks/zod - Retrieved 2026-01-12
3. Zod Best Practices Guide - https://zod.dev/guides/best-practices - Retrieved 2026-01-12
[Writes reference document to ./docs/zod-reference.md]
I have created the reference document at ./docs/zod-reference.md.
**Summary of what is documented:**
- Schema definition and validation basics
- Type inference with z.infer
- Common schema types and modifiers
- Integration patterns for this project
**Sources used:** 3 sources cited
Feel free to ask any questions about Zod...
User: How do I validate nested objects with optional fields?
Assistant: [Checks existing research - answer not fully covered]
[Uses WebSearch for "zod nested objects optional fields"]
[Uses WebFetch on relevant result]
You can validate nested objects with optional fields using z.object() combined with .optional():
const UserSchema = z.object({
name: z.string(),
address: z.object({
street: z.string(),
city: z.string(),
zip: z.string().optional(), // Optional within nested object
}).optional(), // Entire nested object is optional
});
Source: [Zod Nested Objects Guide](https://zod.dev/docs/objects)
Would you like me to add this information to the reference document?
User: Yes, add it.
Assistant: [Uses Edit to update reference document]
I have added this information to the reference document in the Usage > Advanced Usage section.
New source added:
- Zod Nested Objects Guide - https://zod.dev/docs/objects - Retrieved 2026-01-12
Example 2: Reference with Initial Parameters
User: /reference prisma https://www.prisma.io/docs
Assistant: I will create reference documentation for Prisma using the provided documentation URL.
[Uses AskUserQuestion - only asks remaining questions]
I see you want documentation for Prisma. I have the official docs URL. A couple more questions:
1. Where should I save the reference document?
2. Is this reference contextual to your current project?
User: Save to ./docs/prisma-reference.md. Not project-contextual, general reference.
Assistant: Perfect. Creating general-purpose Prisma reference documentation.
[Uses WebFetch on https://www.prisma.io/docs]
[Uses WebSearch for additional Prisma resources]
[Skips codebase exploration since not project-contextual]
[Writes reference document - excludes "Integration with This Project" section]
I have created the reference document at ./docs/prisma-reference.md...
Example 3: Follow-up Question Requiring Research and Testing
User: Does Zod support async validation?
Assistant: [Checks existing research - async validation not covered]
[Uses WebSearch for "zod async validation refine"]
[Uses WebFetch on https://zod.dev/docs/refine]
Yes, Zod supports async validation through .refine() and .superRefine() with async functions. You must use .parseAsync() or .safeParseAsync() when your schema includes async refinements.
I found this requires using parseAsync - would you like me to verify this behavior by testing it?
User: Yes, please verify.
Assistant: [Uses Bash to create and run test file]
Verified: Async validation works as documented. Using .parse() on an async schema throws an error, but .parseAsync() works correctly.
Source: [Zod Refine Documentation](https://zod.dev/docs/refine)
Would you like me to add this information to the reference document?
User: Yes please.
Assistant: [Uses Edit to update reference document]
I have added this information to the reference document:
- Added "Async Validation" subsection under Advanced Usage
- Added example code showing .refine() with async function
- Noted the requirement to use parseAsync/safeParseAsync
- Updated Sources section
New source added:
- Zod Refine Documentation - https://zod.dev/docs/refine - Retrieved 2026-01-12
Update Reference Document
You are tasked with updating an existing reference document by checking its cited sources for changes. You will identify what has changed, update the document accordingly, and provide a clear summary highlighting any breaking changes.
CRITICAL: YOUR PRIORITIES
- Breaking changes are the highest priority - Always identify and prominently call out breaking changes
- Preserve document intent - Update content without restructuring the document
- Source integrity - Maintain accurate source citations with current retrieval dates
- Conservative updates - Only update based on verifiable source changes
Initial Response
When this command is invoked:
If a file path was provided (e.g., /update-reference docs/zod-reference.md):
- Immediately proceed to Step 1
- Do not ask for confirmation
If no file path was provided, respond with:
I'll help you update a reference document by checking its sources for changes.
Please provide the path to the reference document you want to update.
Example: `/update-reference ./docs/my-library-reference.md`
Then wait for the user to provide the file path.
Steps to Follow
Step 1: Read and Parse the Document
-
Read the reference document FULLY using the Read tool
- IMPORTANT: Use the Read tool WITHOUT limit/offset parameters to read the entire file
- This ensures you have complete context before analyzing
-
Extract the Sources section:
- Look for a "## Sources", "## References", or similar section
- Parse all URLs listed (official docs, GitHub repos, blog posts, etc.)
- Note retrieval dates if present
-
If no Sources section found, respond with:
I couldn't find a Sources section in this document. The /update-reference command requires a Sources section with URLs to check for updates. Would you like me to: 1. Help you add a Sources section to this document 2. Search for relevant sources based on the document contentThen wait for the user's response.
-
Catalog the current document structure:
- List all major sections and subsections
- Identify version numbers mentioned (library versions, API versions)
- Note any dated information or timestamps
- Record the current "Last updated" date if present
Step 2: Fetch Current Source Materials
Use WebFetch and WebSearch to retrieve current versions of all sources.
For each source URL:
-
Use WebFetch to retrieve the page content:
- Prompt WebFetch to extract relevant technical information
- Focus on version numbers, API signatures, configuration options
- Request identification of deprecation notices and breaking changes
-
Track the status of each source:
- Available: Successfully fetched, note key findings
- Redirected: Note the new URL, fetch from new location
- Unavailable: Mark for user notification
-
If a source is unavailable, use WebSearch to:
- Find if the content moved to a new URL
- Locate alternative official sources
- Find archived versions if the content was removed
Example WebFetch prompt:
Extract the following from this documentation page:
- Current version number
- API methods and their signatures
- Configuration options and defaults
- Any deprecation notices
- Breaking changes from recent versions
- New features or capabilities
Step 3: Compare and Identify Changes
Analyze differences between the reference document and current source materials.
Categories of changes to identify (in priority order):
-
Breaking Changes (CRITICAL - highest priority):
- Changed behavior that affects existing code
- Removed features or deprecated-then-removed APIs
- Changed function/method signatures
- Changed default values that affect behavior
- Incompatible updates requiring migration
- Minimum version requirement changes
-
Deprecations:
- Newly deprecated methods, options, or patterns
- Timeline for deprecation (if provided)
- Recommended alternatives
-
Version Changes:
- New major/minor/patch versions released
- End-of-life announcements
- LTS status changes
-
API Changes:
- New methods or functions
- New parameters on existing methods
- New return types or properties
-
Configuration Changes:
- New configuration options
- Changed defaults (non-breaking)
- New environment variables
-
New Features:
- New capabilities
- New integrations
- Performance improvements
-
Documentation Updates:
- Clarified instructions
- New examples
- Updated best practices
Step 4: Update the Reference Document
Use the Edit tool to update the document section by section.
Update process:
-
Update affected sections with new information:
- Add warnings for breaking changes inline where relevant
- Mark deprecated content with clear deprecation notices
- Add new content for new features (keep proportional to existing style)
-
Add deprecation markers where needed:
> **Deprecated in v3.0**: The `oldMethod()` function is deprecated. > Use `newMethod()` instead. Will be removed in v4.0. -
Add breaking change warnings inline:
> **Breaking Change (v3.0)**: The `config.timeout` default changed from > 30s to 60s. Existing code relying on the 30s default may need updates. -
Update the Sources section:
- Update retrieval dates to today's date
- Add any new sources used
- Note sources that are no longer available
- Update URLs that have changed
-
Update metadata:
- Update "Last updated" timestamp to today's date
- Update version numbers referenced in the document
-
Add a changelog entry (create section if it doesn't exist):
## Changelog ### YYYY-MM-DD - **Breaking**: [List breaking changes] - **Deprecated**: [List deprecations] - **Added**: [List additions] - **Updated**: [List updates] - **Sources**: [Note source changes]
Step 5: Generate Change Summary
After completing all edits, present a summary to the user:
## Reference Document Update Summary
**Document**: [file path]
**Sources Checked**: [number of sources]
**Sources Available**: [number successfully fetched]
**Update Date**: YYYY-MM-DD
### Breaking Changes
[MOST IMPORTANT - List prominently]
- **[Change]**: [Description] - [Impact on existing code]
- **[Change]**: [Description] - [Migration required]
### Deprecations
- **[Item]**: Deprecated in [version], use [alternative]. Removal planned in [version].
### Version Updates
- [Library/API] updated from [old version] to [new version]
### New Features
- **[Feature]**: [Brief description of capability]
### Other Updates
- **[Section]**: [What changed]
### Source Status
| Source | Status | Notes |
|--------|--------|-------|
| [Name] | Updated | Retrieved YYYY-MM-DD |
| [Name] | URL Changed | Now at [new URL] |
| [Name] | Unavailable | [Reason if known] |
### Sections Modified
- [Section 1]: [Type of change]
- [Section 2]: [Type of change]
---
Would you like me to explain any of these changes in more detail?
Important Guidelines
Prioritize Breaking Changes
- Breaking changes MUST be called out prominently in both the document and summary
- Explain migration paths when available from source documentation
- Note the version where the breaking change occurred
- Add inline warnings in affected sections of the document
Preserve Document Structure
- Do NOT restructure the document significantly
- Keep the original organization and section order
- Add new content in appropriate existing sections
- Only create new sections for major new feature areas
- Preserve any project-specific or custom content
Source Integrity
- Always update source retrieval dates when sources are checked
- Note when sources become unavailable
- Add new sources when using new information
- Keep source URLs accurate (update if redirected)
- Include source retrieval dates in the Sources section
Conservative Update Approach
- Only update based on verifiable source changes
- Do not add speculative or inferred information
- Note uncertainty when sources are ambiguous
- Preserve content that sources do not contradict
- When in doubt, ask the user
Tool Usage
| Tool | Purpose |
|---|---|
| Read | Read the existing reference document (always read FULLY without limit/offset) |
| WebFetch | Retrieve current content from source URLs |
| WebSearch | Find alternative sources, verify information, locate moved content |
| Edit | Update document sections (preferred - use for most updates) |
| Write | Only if document requires complete regeneration (rare, ask user first) |
Error Handling
No Sources Section Found
This document doesn't have a Sources section with URLs to check.
I cannot verify updates without knowing the original sources.
Options:
1. Add a Sources section manually with relevant URLs, then run /update-reference again
2. I can help you identify likely sources based on the document content
3. Use /reference to recreate the document with proper source citations
Which would you prefer?
All Sources Unavailable
I couldn't reach any of the [N] sources listed in this document.
This might be due to:
- Temporary network issues
- Sources have been permanently removed
- URLs have changed and need updating
Would you like me to:
1. Search for alternative sources for [topic]?
2. Preserve current content and note that sources couldn't be verified?
3. Try again later?
Some Sources Unavailable
I was able to fetch [X] of [Y] sources. The following were unavailable:
- [Source 1]: [URL] - [Error/reason if known]
- [Source 2]: [URL] - [Error/reason if known]
I can:
1. Proceed with available sources and note the unavailable ones
2. Search for alternative sources for the unavailable content
3. Wait while you verify the URLs
How would you like to proceed?
Major Structural Changes in Source
The source documentation for [library/topic] has been significantly restructured.
Key changes detected:
- [List major structural changes]
Rather than making many fragmented updates, I recommend:
1. Review the structural changes first (I can summarize)
2. Consider regenerating the reference with /reference
3. Or I can attempt incremental updates (may be incomplete)
Which approach would you prefer?
Version Mismatch
The document references [library] version [X], but the current version is [Y].
This is a [major/minor/patch] version difference, which typically means:
- [Explain implications based on semver]
Would you like me to:
1. Update the document to reflect version [Y]
2. Keep the document at version [X] (if intentionally pinned)
3. Create a note about version differences without updating
Example Interaction Flows
Standard Update Flow
User: /update-reference docs/react-query-reference.md
Assistant: I'll check the sources in your React Query reference document for updates.
[Reads the document using Read tool]
I found 4 sources in your reference document:
- Official docs: https://tanstack.com/query/latest (retrieved 2025-06-15)
- GitHub: https://github.com/TanStack/query
- Migration guide: https://tanstack.com/query/latest/docs/react/guides/migrating-to-v5
- Blog post: https://tkdodo.eu/blog/practical-react-query
Let me fetch current content from these sources...
[Uses WebFetch on each source URL]
## Reference Document Update Summary
**Document**: docs/react-query-reference.md
**Sources Checked**: 4
**Sources Available**: 4
**Update Date**: 2026-01-12
### Breaking Changes
- **Default staleTime**: Changed from 0 to 5 minutes in v5.1 - Code relying on immediate refetches may behave differently
- **useQuery signature**: Object-only syntax now required - Must include queryKey in all useQuery calls
### Deprecations
- **onSuccess/onError callbacks**: Deprecated in v5.0, use useEffect instead. Removal planned in v6.0.
### Version Updates
- TanStack Query updated from v5.0 to v5.59
### New Features
- **useSuspenseQuery**: New hook for React Suspense integration
- **queryOptions**: Type-safe query configuration helper
### Source Status
| Source | Status | Notes |
|--------|--------|-------|
| Official docs | Updated | Retrieved 2026-01-12 |
| GitHub | Updated | Retrieved 2026-01-12 |
| Migration guide | Updated | Retrieved 2026-01-12 |
| Blog post | Updated | Retrieved 2026-01-12 |
I've updated the document with these changes. Would you like me to explain any of them in more detail?
Update with Unavailable Sources
User: /update-reference docs/legacy-api-reference.md
Assistant: I'll check the sources in your legacy API reference document.
[Reads the document]
I found 3 sources:
- API docs: https://old-api.example.com/docs
- GitHub wiki: https://github.com/example/old-api/wiki
- Blog announcement: https://blog.example.com/old-api-launch
Let me fetch current content...
[Attempts WebFetch on each URL]
I was able to fetch 1 of 3 sources. The following were unavailable:
- API docs: https://old-api.example.com/docs - 404 Not Found
- Blog announcement: https://blog.example.com/old-api-launch - Domain expired
I can:
1. Proceed with the GitHub wiki and note the unavailable sources
2. Search for alternative documentation sources
3. Wait while you verify the URLs
User: Let's proceed with what we have and search for alternatives
Assistant: I'll update using the available source and search for alternatives.
[Uses WebSearch to find alternative documentation]
I found an archived version of the API docs on the Wayback Machine and the project has moved to a new repository.
## Reference Document Update Summary
**Document**: docs/legacy-api-reference.md
**Sources Checked**: 3
**Sources Available**: 1 (+ 1 archived, 1 new location found)
**Update Date**: 2026-01-12
### Source Status
| Source | Status | Notes |
|--------|--------|-------|
| API docs | Unavailable | Found archived version at web.archive.org |
| GitHub wiki | Updated | Retrieved 2026-01-12 |
| Blog | Unavailable | Domain expired, no archive found |
### Updates Made
- Added note about API documentation being archived
- Updated GitHub link to new repository location
- Marked blog source as unavailable in Sources section
No breaking changes were identified in the available sources.
No Changes Found
User: /update-reference docs/stable-library-reference.md
Assistant: I'll check the sources in your stable library reference document.
[Reads document and fetches all sources]
## Reference Document Update Summary
**Document**: docs/stable-library-reference.md
**Sources Checked**: 3
**Sources Available**: 3
**Update Date**: 2026-01-12
### No Changes Detected
All source content matches the current documentation. The reference document is up to date.
### Source Status
| Source | Status | Notes |
|--------|--------|-------|
| Official docs | No changes | Content unchanged since last update |
| GitHub README | No changes | Same version (v2.4.1) |
| API reference | No changes | All methods match documentation |
I've updated the retrieval dates in the Sources section to reflect today's check. No other changes were necessary.
Important Notes
-
Critical ordering: Always follow the numbered steps in sequence
- Step 1: Read the document FULLY before analyzing
- Step 2: Fetch ALL sources before comparing
- Step 3: Complete analysis before making any edits
- Step 4: Make all edits before generating summary
- Step 5: Present complete summary at the end
-
Breaking changes first: When presenting findings, always lead with breaking changes
-
Preserve user content: If the document contains project-specific notes, examples, or customizations not from the sources, preserve them unchanged
-
Version pinning: If a document appears intentionally pinned to an older version (noted in metadata or comments), ask before updating to newer versions
-
Changelog hygiene: Add new changelog entries at the TOP of the changelog section, keeping history in reverse chronological order
-
Source date format: Use ISO date format (YYYY-MM-DD) for all retrieval dates in the Sources section
Sponsors
Details
- Marketplace
- jeffh/claude-plugins
- Source
- discuss
- Author
- Jeff Hui
- Category
- Productivity