---
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` or higher AND you are Sonnet or Opus.
If effort is 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`:

```json
{
  "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).
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:select-project")`.
   - If CWD doesn't match any project → proceed without warning (shared directory).
3. 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

| Category | Signal | Single file section | Directory mode file |
|----------|--------|---------------------|---------------------|
| New feature | Discussion of new capability | §3 Feature List (new subsection) | `03-features/<feature-code>.md` (new file) |
| New requirement | "System should..." statements | §3.X EARS Requirements | `03-features/<feature-code>.md` (existing file) |
| Requirement change | Modifying existing behavior | §3.X EARS Requirements (edit) | `03-features/<feature-code>.md` (edit) |
| NFR change | Performance, security, scale discussion | §2 Non-functional | `02-non-functional.md` |
| Scope change | "Out of scope" or "must have for launch" | §3.X In/Out of scope | `03-features/<feature-code>.md` (edit) |
| Open question | Unresolved product decision | §5 Open Questions | `05-open-questions.md` |
| Question resolved | Answer to existing OQ | §5 Open Questions (remove) | `05-open-questions.md` (remove) |

## Step 3: Propose Updates

For each detected change, propose a specific update:

```markdown
## 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/`
3. **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
4. Maintain requirement ID sequence (find highest PRD-XXX-REQ-NNN, increment)
5. Update "Last updated" timestamp
6. 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:

| Pattern | Template |
|---------|----------|
| Event-Driven | When `<trigger>` then the system shall `<response>` |
| State-Driven | While `<state>` the system shall `<behavior>` |
| Unwanted | If `<condition>` then the system shall `<mitigation>` |
| Optional | Where `<feature enabled>` the system shall `<behavior>` |

## 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:

```markdown
## 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