Sync Specs from Session

What this skill does

# Sync Specs from Session

Analyze the current session context to identify implemented features, compare with existing SPECLAN specifications, and create or update specs based on user confirmation.

## Core Principle: Implementation-Agnostic Specs

**SPECS MUST NEVER CONTAIN IMPLEMENTATION OR ARCHITECTURE DETAILS.** This skill analyzes code changes internally to understand WHAT was built, but specs describe only user-facing capabilities and business value. Never include file paths, code references, library names, technical approaches, architectural decisions, design patterns, or any implementation-specific information in generated specs.

## When to Use

- After completing implementation work and wanting to document it
- When user asks to sync or update specs based on recent work
- To capture newly implemented functionality in SPECLAN format

## Workflow Overview

```
1. Analyze Session → 2. Scan Speclan → 3. Compare & Diff → 4. Ask User → 5. Apply Changes
```

## Step 1: Analyze Session Context

Review the conversation history to identify:

### 1.1 Code Changes Made (Internal Analysis)

Look for patterns indicating implementation (for internal matching only - these details are NOT included in specs):
- Files created or modified (Write/Edit tool usage)
- Functions, classes, or components added
- API endpoints implemented
- Database schema changes
- Configuration updates

**Purpose:** Use these implementation signals to identify WHAT was built, then translate into user-facing capability descriptions for specs.

### 1.2 Extract Feature Information

For each identified change, extract:

```yaml
feature_candidate:
  title: "<descriptive name>"
  description: "<what it does for users and why it matters>"
  _code_paths: ["<files involved>"]  # INTERNAL USE ONLY - for matching, never included in specs
  type: "new" | "enhancement" | "bugfix"
  scope: "feature" | "requirement" | "both"
  _status_evidence:                  # INTERNAL USE ONLY - for status determination
    has_tests: true | false
    tests_pass: true | false | unknown
    is_partial: true | false
```

**Note:** `_code_paths` and `_status_evidence` are used internally. They are NEVER written to spec files.

### 1.2a Determine Status for Each Feature

Sync-from-session runs after the user has already been coding ("vibe coding"), so the code already exists. The spec status must reflect where the implementation actually is — never `draft` or `approved` (those are pre-implementation states).

**Determine status from evidence:**

| Tests exist? | Tests pass? | Code complete? | Status |
|---|---|---|---|
| Yes | Yes | Yes | `under-test` |
| Yes | Some fail | Yes | `in-development` |
| Yes | Unknown (not run) | Yes | `in-development` |
| No | N/A | Yes | `in-development` |
| N/A | N/A | Partial | `in-development` |

**How to gather evidence:**
1. Search for test files matching the implementation (`*.test.*`, `*.spec.*` in the same area)
2. Check the session history — did tests run? Did they pass?
3. Check for TODO/FIXME markers or incomplete implementations in the code
4. If uncertain, default to `in-development` — it's the safest post-implementation status

The determined status applies to new features, new requirements, and new change requests created by this sync.

### 1.3 Categorize Changes

Group related changes into logical features:
- Multiple file changes for one feature = single feature
- Independent changes = separate features
- Small fixes to existing features = requirement updates

## Step 2: Scan Speclan Directory

### 2.1 Detect Speclan Location

```bash
# Check common locations
if [ -d "speclan" ]; then
  SPECLAN_DIR="speclan"
elif [ -d "specs/speclan" ]; then
  SPECLAN_DIR="specs/speclan"
else
  # No speclan directory - all features are new
  SPECLAN_DIR=""
fi
```

### 2.2 Index Existing Specs

If speclan directory exists, build an index:

```bash
# List all features
find "$SPECLAN_DIR/features" -name "F-*.md" -type f 2>/dev/null

# Extract titles and paths
for f in $(find "$SPECLAN_DIR/features" -name "F-*.md" -type f); do
  id=$(grep "^id:" "$f" | head -1 | cut -d: -f2 | tr -d ' ')
  title=$(grep "^title:" "$f" | head -1 | cut -d: -f2-)
  echo "$id|$title|$f"
done
```

### 2.3 Build Existing Spec Map

Create a mapping of:
- Feature ID → Title → File path (spec file location, not code)
- Feature ID → Status (for edit rules)
- Feature ID → Key capabilities (for semantic matching)

**Note:** Use titles and capability descriptions for matching, not code paths. Well-formed specs should not contain implementation or architecture references.

## Step 3: Compare and Generate Diff

### 3.1 Match Session Work to Existing Specs

For each feature candidate from session:

1. **Title similarity check**: Compare with existing feature titles
2. **Capability overlap**: Check if the described functionality matches existing features
3. **Description similarity**: Semantic comparison of purpose and user-facing behavior

**Note:** Matching is based on functional capabilities and user outcomes, not on code paths, implementation details, or architectural decisions.

### 3.2 Classify Each Change

| Session Feature | Existing Spec | Classification |
|-----------------|---------------|----------------|
| New capability | No match | **CREATE** new feature |
| Related capability | Match found, status editable | **UPDATE** existing feature |
| Related capability | Match found, status locked | **CHANGE_REQUEST** needed |
| Enhancement | Partial match | **ADD_REQUIREMENT** to feature |

### 3.3 Prepare Change Summary

Build a structured summary:

```yaml
# NOTE: _code_paths are INTERNAL ONLY for matching - never written to specs
changes:
  create:
    - title: "User Authentication"
      description: "Secure login with automatic session refresh"
      _code_paths: ["src/auth/", "src/middleware/auth.ts"]  # internal matching only

  update:
    - id: "F-1142"
      title: "Pet Management"
      changes: "Added bulk import capability for pet records"
      _code_paths: ["src/pets/import.ts"]  # internal matching only

  change_requests:
    - parent_id: "F-1089"
      title: "Add Export Feature"
      reason: "Feature is in-development status"

  requirements:
    - feature_id: "F-1142"
      title: "Validate CSV format on import"
      _code_paths: ["src/pets/validators/csv.ts"]  # internal matching only
```

## Step 4: Ask User for Confirmation

Present the identified changes to the user using AskUserQuestion or direct prompting.

### 4.1 Summary Format

```markdown
## Identified Changes from Session

Based on our session, I identified the following potential spec updates:

### New Features to Create
1. **User Authentication** - Secure login with automatic session refresh

### Existing Features to Update
1. **F-1142 Pet Management** - Add bulk import capability for pet records
   - Current status: draft (editable)

### Change Requests Needed
1. **F-1089 Data Export** - Feature is locked (in-development)
   - Proposed: Add export option for user data

### New Requirements
1. For **F-1142**: Validate file format on import
```

**IMPORTANT:** Keep descriptions implementation-agnostic (see `references/implementation-agnostic-guidelines.md`).

### 4.2 Ask for User Selection

Use AskUserQuestion to let user choose:

```yaml
questions:
  - question: "Which changes would you like to apply to specs?"
    header: "Apply"
    multiSelect: true
    options:
      - label: "Create: User Authentication"
        description: "New feature for secure login with session refresh"
      - label: "Update: F-1142 Pet Management"
        description: "Add bulk import capability to existing feature"
      - label: "CR for F-1089: Data Export"
        description: "Create change request for locked feature"
      - label: "Requirement for F-1142"
        description: "Add file format validation requirement"
```

### 4.3 Handle User Response

- **Selected items**: Proceed to create/update
- **"Other" response**: User may provide custom