source-product-specs-from-code · diff

git:20260622.e142476 to git:20260624.e533827

2 added, 2 removed. Audit A to A.

---

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.

+ 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`:

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

|----------|--------|---------------------|---------------------|

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