version: "1.0.0" name: source-product-specs-from-code description: Synchronize PRD with implemented codebase changes. Usage /groundwork:source-product-specs-from-code argument-hint: "[files...]" allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "Skill"] disable-model-invocation: true

Sync Product Specs Skill

Keeps {{specs_dir}}/product_specs.md synchronized with product decisions made during sessions.

Pre-flight: Model Recommendation

Your current effort level is `{{effort_level}}`.

Skip this step silently if effort is high, xhigh, or max (the scale is low < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Sonnet or Opus. If effort is low or medium (i.e. below high), you MUST show the recommendation prompt — regardless of model. If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Session change detection and EARS requirement update quality benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
    "header": "Recommended: Sonnet or Opus 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 loading specs, ensure project context is resolved:

1. Monorepo check: Does .groundwork.yml exist at the repo root?

• If yes → Is {{project_name}} non-empty?
• If empty → Invoke Skill(skill="groundwork:select-project") to select a project, then restart this skill.
• If set → Project is {{project_name}}, specs at {{specs_dir}}/.
• If no → Continue (single-project repo).

1. 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:select-project").

• If CWD doesn't match any project → proceed without warning (shared directory).

1. Proceed with the resolved project context. All {{specs_dir}}/ paths will resolve to the correct location.

File Locations

• Target: Product specs (may be single file or directory)
• Single file: {{specs_dir}}/product_specs.md
• Directory: {{specs_dir}}/product_specs/ (content split across files)
• Context: Current session history

Detection: Check for single file first (takes precedence), then directory.

When to Trigger

This skill should activate when:

• User explicitly invokes /groundwork:source-product-specs-from-code
• Session involved product decisions (new features, requirement changes)
• User feedback changed scope or priorities
• New edge cases or requirements were discovered

Workflow Overview

1. Analyze Session - Review product-relevant discussions
2. Detect Changes - Identify PRD implications
3. Propose Updates - Draft EARS requirements or modifications
4. Apply Changes - Update document with user approval

Step 1: Analyze Session

Review the current session for:

New Requirements:

• "We also need to handle X"
• "What if the user does Y?"
• "Add support for Z"

Requirement Changes:

• "Actually, that should be 5 attempts, not 3"
• "Let's make that optional"
• "Remove the email notification"

Scope Changes:

• "Let's defer that to v2"
• "That's out of scope"
• "We need to add this for launch"

New Edge Cases:

• Error conditions discovered during implementation
• User feedback revealing gaps
• Integration constraints

Step 2: Detect Change Categories

Step 3: Propose Updates

For each detected change, propose a specific update:

## Proposed PRD Updates
 
### 1. New Requirement
 
**Trigger:** You discussed that artists should be warned before their quota expires.
 
**Proposed addition to §3.3 Monetization:**
 
-`PRD-MON-REQ-005` When artist quota falls below 10% remaining then the system shall send a warning notification via email.
 
---
 
### 2. Requirement Modification
 
**Trigger:** Changed impersonation lockout from N to 5 attempts.
 
**Current:** 
-`PRD-IMP-REQ-008` When impersonation attempts exceed N per day by same user then the system shall lock account pending admin review.
 
**Proposed:**
-`PRD-IMP-REQ-008` When impersonation attempts exceed 5 per day by same user then the system shall lock account pending admin review.
 
---
 
### 3. New Open Question
 
**Trigger:** Unresolved discussion about handling rate limits.
 
**Proposed addition to §5:**
 
-`OQ-008` How should the system handle rate-limited users - queue requests or reject immediately?
 
---
 
### 4. Scope Change
 
**Trigger:** Multi-artist collaborative models deferred to v2.
 
**Proposed update to §3.1 Out of scope:**
 
Add: "Multi-artist collaborative models (deferred to v2)"
 
---
 
Approve these updates? (yes/no/modify)

Step 4: Apply Changes

On approval:

1. Detect spec format - Check if PRD is single file or directory
2. Read current content:

• Single file: Read {{specs_dir}}/product_specs.md
• Directory: Aggregate all .md files from {{specs_dir}}/product_specs/

1. Route updates to appropriate files:

• Single file mode: Edit {{specs_dir}}/product_specs.md directly
• Directory mode: Route each update:
• Features with ID (e.g., PRD-AUTH-*) → Find or create in {{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
• Updates to existing content → Find the file containing that content

1. Maintain requirement ID sequence (find highest PRD-XXX-REQ-NNN, increment)
2. Update "Last updated" timestamp
3. Update "Doc status" if appropriate

Important:

• New requirements get the next available ID in their feature's sequence
• Never reuse deleted requirement IDs (maintain traceability)
• Preserve EARS format for all requirements

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

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

After applying changes 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-specs") — this runs automatically with no user input needed.
• After the split completes, include in the session summary: "The PRD was automatically split into directory format at {{specs_dir}}/product_specs/."

If neither threshold is crossed, continue silently.

EARS Format Reminder

All requirements must follow EARS syntax:

Change Detection Heuristics

Strong signals (likely PRD change):

• User explicitly states a requirement
• Edge case discovered that needs handling
• User feedback contradicting current spec
• "Must have for launch" statements
• Explicit scope decisions

Weak signals (maybe PRD change):

• Implementation difficulties (might be architecture, not requirements)
• Performance optimizations (might be NFR or architecture)
• UI/UX discussions (might be design, not requirements)

Focus on strong signals. For weak signals, ask: "Should this be captured as a product requirement, or is it an implementation/design detail?"

Session Summary Format

At session end, provide summary:

## PRD Sync Summary
 
**Session Date:** [date]
 
### Changes Detected:
1.[Change 1] → New requirement PRD-XXX-REQ-NNN
2.[Change 2] → Modified PRD-YYY-REQ-NNN
3.[Change 3] → Added open question OQ-NNN
4.[Change 4] → No PRD impact (implementation detail)
 
### PRD Document:
-[X] Updated with approved changes
-[ ] No changes needed
-[ ] Changes pending user review
 
### Requirement IDs Added/Modified:
-PRD-XXX-REQ-NNN (new)
-PRD-YYY-REQ-NNN (modified)
 
### Open Items:
-[Any unresolved product questions from session]

Interaction with Other Skills

This skill works in concert with:

• /groundwork:design-product - For deliberate, interactive requirement creation
• /groundwork:source-architecture-from-code - PRD changes may trigger architecture updates

When both /groundwork:source-product-specs-from-code and /groundwork:source-architecture-from-code run:

1. Run /groundwork:source-product-specs-from-code first (product drives architecture)
2. Note any new requirements that may need architectural support
3. Run /groundwork:source-architecture-from-code with awareness of PRD changes