Product Design

Skip this step silently if effort is high or higher AND you are Opus (1M context). If effort is below high, you MUST show the recommendation prompt — regardless of model. If you are not Opus (1M context), you MUST show the recommendation prompt - regardless of model.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Cross-spec contradiction detection across PRD, architecture, and design system benefits from deeper reasoning.\n\nTo switch: cancel, run `/model opus[1m]` and `/effort high`, then re-invoke this skill.",
    "header": "Recommended: Opus (1M context) at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

Step 0: Resolve Project Context

Before anything else, resolve the project context:

1. Monorepo check: Does .groundwork.yml exist at the repo root?
   • If yes → Is {{project_name}} non-empty?
     • If empty → Invoke Skill(skill="groundwork:project-selector") to select a project, then restart this skill.
     • If set → Project is {{project_name}}, specs at {{specs_dir}}/.
   • If no → Continue to item 3.
2. CWD mismatch check (monorepo only):
   • Skip if not in monorepo mode or if the project was just selected in item 1 above.
   • If CWD is the repo root → fine, proceed.
   • Check which project's path CWD falls inside (compare against all projects in .groundwork.yml).
   • If CWD is inside the selected project's path → fine, proceed.
   • If CWD is inside a different project's path → warn via AskUserQuestion:

     "You're working from <cwd> (inside [cwd-project]), but the selected Groundwork project is [selected-project] ([selected-project-path]/). What would you like to do?"

     • "Switch to [cwd-project]"
     • "Stay with [selected-project]" If the user switches, invoke Skill(skill="groundwork:project-selector").

   • If CWD doesn't match any project → proceed without warning (shared directory).
3. Check {{specs_dir}}/: Does a specs directory exist?
   • If yes → Single-project repo, proceed normally.
   • If no → Ask the user: "Is this a single-project repo or a monorepo with multiple projects?"
     • Single project → Proceed normally (specs will be created at {{specs_dir}}/)
     • Monorepo → Invoke Skill(skill="groundwork:repo-setup") to create .groundwork.yml, then continue.

Step 0a: Feature-Project Mismatch Check (monorepo only)

Skip this check if:

• Not in monorepo mode (no .groundwork.yml)
• The project was just selected as part of Step 0 above (the user explicitly chose)
• The CWD mismatch check in Step 0 triggered a project switch

If in monorepo mode with a previously selected project:

• Evaluate whether the requested feature "sounds like" it belongs to the selected project
• If a mismatch is detected (e.g., user asks to design "push notifications for mobile" but web-app is selected):

  "This feature sounds like it might belong to [other-project] rather than [current-project]. Continue with [current-project] or switch?"

• If the user confirms the current project, proceed normally
• If the user wants to switch, invoke Skill(skill="groundwork:project-selector") and then continue

Step 0b: Do we have context?

If the user called the skill without any context, ask them to provide context on what feature they want to add, modify or remove.

Step 0c: Load Project Context

Before clarifying the request, load existing specs so you can detect contradictions and understand constraints:

Check for and read (if they exist):

• {{specs_dir}}/architecture.md (or {{specs_dir}}/architecture/ directory) — technology choices, component boundaries, decision records. Use to catch architecturally infeasible requirements early.
• {{specs_dir}}/design_system.md — design principles, brand decisions, UX patterns. Use to ensure new features align with established design language.
• {{specs_dir}}/product_specs.md (or {{specs_dir}}/product_specs/ directory) — already loaded implicitly by the contradiction check, but read it explicitly here for full cross-feature context.

For each, check single file first, then directory. If a directory, aggregate all .md files.

If none exist, that's fine — proceed without them.

Step 1: Understand the Request

Invoke the groundwork:understanding-feature-requests skill to clarify the feature and check for contradictions.

If architecture and design system were loaded in Step 0.5, provide them as context so the clarification can also check for:

• Architectural feasibility — requirements that conflict with technology choices or component boundaries
• Design consistency — features that would require patterns contradicting the established design system

This skill will:

1. Ask clarifying questions (core, exploratory, conditional)
2. Check for internal, cross-feature, and technical contradictions
3. Resolve any conflicts before proceeding

Once understanding is complete and conflicts resolved, continue to Step 2.

Step 2: Design EARS Requirements

Once the feature is understood, draft requirements using EARS syntax.

EARS Syntax Reference

Requirement Quality Checklist

Each requirement must be:

• Atomic - One behavior per requirement
• Testable - Clear pass/fail criteria exist
• Technology-agnostic - No implementation details
• Unambiguous - Single interpretation possible
• Traceable - Has unique ID following project convention

ID Convention

Follow the existing PRD convention: PRD-<FEATURE>-REQ-<NNN>

Examples from the project:

• PRD-FINE-REQ-001 (Finetuning feature)
• PRD-GEN-REQ-001 (Generation feature)
• PRD-IMP-REQ-001 (Impersonation detection)
• PRD-MON-REQ-001 (Monetization)
• PRD-DEL-REQ-001 (Data deletion)

For new features, propose a short code (3-4 chars) and confirm with user.

Check for Contradictions

Before presenting the draft, review for conflicts:

Cross-Feature Conflicts

Compare new requirements against existing PRD:

• Behavioral conflicts: New behavior contradicts existing behavior
• Resource competition: Features that compete for same limited resources
• UX inconsistency: Different patterns for similar interactions
• Data conflicts: Contradictory data ownership or access rules

Example: New "anonymous posting" requirement conflicts with existing "all user actions must be audited"

Technical Incompatibilities

Requirements that may be technically difficult to satisfy together:

• Performance constraints that conflict
• Security requirements that limit functionality
• Scalability needs that conflict with simplicity

If conflicts found, surface them:

"I noticed a potential conflict:

• [Existing requirement or pattern] requires [X]
• This new requirement requires [Y] These may be incompatible because [reason].

Options:

1. Modify the new requirement to [alternative]
2. Update the existing requirement
3. Accept the conflict as a known trade-off

How should we resolve this?"

After resolution:

• If user chooses option 1 (modify new): Update the draft requirement and re-present
• If user chooses option 2 (update existing): Note the PRD change needed and proceed
• If user chooses option 3 (accept trade-off): Document the trade-off in the feature block and proceed

Do not proceed to Step 3 until conflicts are resolved or explicitly accepted.

Present Progressively

When presenting complex feature blocks:

• Break into 200-300 word segments
• Seek confirmation after each section before continuing
• Start with problem/outcome, then scope, then requirements
• This catches misunderstandings early and keeps stakeholders engaged

Step 3: Present Draft for Approval

Before editing the PRD, present the complete feature block:

### [Feature Number] Feature Name

**Problem / outcome**
[1-2 sentences describing the problem and desired outcome]

**In scope**
- [Capability 1]
- [Capability 2]

**Out of scope**
- [Explicit exclusion 1]

**EARS Requirements**
- `PRD-XXX-REQ-001` When [trigger] then the system shall [response].
- `PRD-XXX-REQ-002` When [trigger] then the system shall [response].

**Acceptance criteria**
- [Testable criterion 1]
- [Testable criterion 2]

**Telemetry** (optional)
- [Metric to track]

**Rollout** (optional)
- Phase 1: [description]
- Phase 2: [description]

Ask: "Does this capture your requirements? Any changes before I update the PRD?"

Scope discipline:

• Apply YAGNI thinking - challenge every "nice to have"
• Ask: "What's the simplest version that delivers the core value?"
• If scope feels large, propose a phased approach

Step 4: Commit to PRD

If in plan mode: The plan should describe only the file edits in this step — which file to edit, where to insert, and what content to write. Do not plan architecture, code, or technical implementation of the feature.

PRD Location: The PRD may be stored as:

• Single file: {{specs_dir}}/product_specs.md
• Directory: {{specs_dir}}/product_specs/ (with content split across files)

When the user approves:

1. Check if PRD exists - Look for single file first, then directory

   • If missing, create {{specs_dir}}/product_specs.md using the template in references/prd-template.md
   • Ensure {{specs_dir}}/ directory exists first

2. Route the content - Determine where to write based on spec format:

   • Single file mode: Edit {{specs_dir}}/product_specs.md directly
   • Directory mode: Route to appropriate file:
     • Features with ID (e.g., PRD-AUTH-*) → {{specs_dir}}/product_specs/03-features/<feature-code>.md
     • Open questions → {{specs_dir}}/product_specs/05-open-questions.md
     • NFR changes → {{specs_dir}}/product_specs/02-non-functional.md
     • Product context changes → {{specs_dir}}/product_specs/01-product-context.md
     • Traceability updates → {{specs_dir}}/product_specs/04-traceability.md

3. Find insertion point - New features go in Section 3 (Feature list) after existing features

4. Edit the document - Use str_replace to insert the new feature block

5. Update open questions - If any remain, add to Section 5 (Open questions log)

6. Update traceability note - Mention new requirement IDs if relevant

After editing, confirm: "I've added [feature] to the PRD with requirements PRD-XXX-REQ-001 through PRD-XXX-REQ-NNN."

Step 4a: Auto-Split Check (single file mode only)

Skip this step if the PRD is already in directory mode.

After committing to the single-file PRD, check whether it should be split:

1. Count lines: wc -l {{specs_dir}}/product_specs.md
2. Count features: number of ### \d+\.\d+ headings in the file

If lines >= 500 OR features >= 15:

• Invoke Skill(skill="groundwork:split-specifications") — this runs automatically with no user input needed.
• After the split completes, note in your confirmation: "The PRD has been split into directory format at {{specs_dir}}/product_specs/ for easier navigation."

If neither threshold is crossed, continue silently.

Step 5: Ask What's Next

After successfully updating the PRD, use the AskUserQuestion tool to present the next step options:

{
  "questions": [{
    "question": "What would you like to do next?",
    "header": "Next step",
    "options": [
      {
        "label": "Design architecture",
        "description": "Translate these requirements into technical architecture decisions"
      },
      {
        "label": "Design UX",
        "description": "Create user experience designs and flows for this feature"
      },
      {
        "label": "Create tasks",
        "description": "Generate implementation tasks for this feature"
      },
      {
        "label": "Add another feature",
        "description": "Continue adding more features to the PRD"
      }
    ],
    "multiSelect": false
  }]
}

Handle the response:

• Design architecture: Invoke the groundwork:architecture skill to design the technical approach
• Design UX: Invoke the groundwork:ux-design skill to create UX designs
• Create tasks: Invoke the groundwork:tasks skill to generate implementation tasks for the new feature
• Add another feature: Clear context by summarizing what was just added, then restart from Step 1 with a fresh feature request. Ask: "What feature would you like to add next?"

Conversation Patterns

Adding a New Feature

User: I want to add a feature for artists to share their portfolios publicly.

Claude: Great idea! Let me understand this better:
1. What should be shareable - just the generated outputs, or training images too?
2. Should other users be able to interact (like/comment) or just view?
3. Are there privacy controls the artist should have?

[User answers...]

Claude: Based on your answers, here's what I'm proposing:

### 3.X Portfolio Sharing

**Problem / outcome**
Artists want to showcase their AI-generated work publicly to attract commissions.

**In scope**
- Public gallery page per artist
- ...

**EARS Requirements**
- `PRD-PORT-REQ-001` When an artist enables public portfolio then the system shall...

Does this capture it? Any changes?

Modifying an Existing Requirement

User: PRD-IMP-REQ-008 should lock the account after 5 attempts, not N.

Claude: I'll update PRD-IMP-REQ-008 to specify 5 attempts:

**Before:** When impersonation attempts exceed N per day...
**After:** When impersonation attempts exceed 5 per day...

Should I also add a configuration option for admins to adjust this threshold, or keep it fixed at 5?

Clarifying Ambiguity

User: Add a requirement for faster generation.

Claude: "Faster" needs to be specific for a testable requirement. Currently PRD specifies p95 < 2s.
- What latency target do you have in mind? (e.g., p95 < 1s, p99 < 2s)
- Does this apply to all generation types or specific ones?
- Are there trade-offs you'd accept (e.g., lower quality for speed)?

Reference Files

For detailed examples of well-written EARS requirements, see:

• references/ears-examples.md - Curated examples from various domains
• references/prd-template.md - Template for creating new PRD files