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:

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"

Note: _code_paths is used internally to match session work to existing specs. It is NEVER written to spec files.

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

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

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

# 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

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

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 instructions
• No selection: Skip spec updates

Step 5: Apply Changes

5.1 Generate IDs

For new entities, generate collision-free IDs:

SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs"

# Generate a feature ID
FEATURE_ID=$(node "$SCRIPT" --type feature --speclan-root "$SPECLAN_DIR" | jq -r '.data.ids[0]')

# Generate a requirement ID under a parent feature
REQ_ID=$(node "$SCRIPT" --type requirement --parent "$FEATURE_ID" --speclan-root "$SPECLAN_DIR" | jq -r '.data.ids[0]')

5.2 Create New Features

For each new feature:

1. Create directory structure:

   mkdir -p "$SPECLAN_DIR/features/F-####-slug"
   mkdir -p "$SPECLAN_DIR/features/F-####-slug/requirements"
   

2. Write feature file with YAML frontmatter:

   ---
   id: F-####
   type: feature
   title: <Title>
   status: under-test
   owner: <from session or "Developer">
   created: "<ISO-8601>"
   updated: "<ISO-8601>"
   goals: []
   ---
   
   # <Title>
   
   ## Overview
   <Description from session analysis - focus on WHAT and WHY, not HOW>
   
   ## Scope
   <Bullet points of functionality - user-facing capabilities, not code details>
   

Specs must be 100% implementation and architecture agnostic. For the complete DO/DON'T list with examples, consult references/implementation-agnostic-guidelines.md.

5.3 Update Existing Features

For features with editable status (draft, review, approved):

1. Read current file
2. Update relevant sections:
   • Add new scope items (user-facing capabilities only)
   • Update description if needed (keep implementation-agnostic)
3. Update updated timestamp
4. Write file back

Remember: Never add implementation details, architecture decisions, code references, or technical approaches to existing specs.

5.4 Create Change Requests

For locked entities (features or requirements in-development, under-test, released):

1. Generate CR ID:

   CR_ID=$(node "$SCRIPT" --type change-request --speclan-root "$SPECLAN_DIR" | jq -r '.data.ids[0]')
   

2. Create CR file:

   ---
   id: CR-####
   type: changeRequest
   title: <Change title>
   status: under-test
   owner: Developer
   created: "<ISO-8601>"
   updated: "<ISO-8601>"
   parentId: <F-#### or R-####>
   parentType: <feature or requirement>
   changeType: enhancement
   description: <Brief description - user-facing, no implementation details>
   changes: |
     <Detailed change narrative - describe WHAT changes for users, not HOW it's implemented>
   ---
   

   Note: Change request descriptions must also be implementation-agnostic (see guidelines).

3. Place in correct location (adjacent to target entity):

   # For features:
   speclan/features/F-####-slug/change-requests/CR-####-slug.md
   
   # For requirements:
   speclan/features/.../requirements/R-####-slug/change-requests/CR-####-slug.md
   

5.5 Create New Requirements

For requirements under existing features:

1. Generate requirement ID
2. Create requirement directory structure:

   mkdir -p "speclan/features/F-####-parent/requirements/R-####-slug"
   

3. Write requirement file:

   speclan/features/F-####-parent/requirements/R-####-slug/R-####-slug.md
   

4. Update parent feature's updated timestamp

Step 6: Report Results

After applying changes, report:

## Spec Sync Complete

### Created
- F-#### User Authentication (speclan/features/F-####-user-authentication/)
- R-#### CSV Validation (speclan/features/F-1142-pet-management/requirements/R-####-csv-validation/)

### Updated
- F-1142 Pet Management - added bulk import scope

### Change Requests Created
- CR-#### for F-1089 Data Export (speclan/features/F-1089-.../change-requests/)
- CR-#### for R-#### (speclan/.../requirements/R-####-.../change-requests/)

### Next Steps
- Review created specs for accuracy
- Assign goals to new features
- Process pending change requests

Edge Cases

No Speclan Directory

If speclan/ doesn't exist:

1. Ask user if they want to initialize it
2. If yes, create basic structure:

   mkdir -p speclan/goals speclan/features speclan/templates
   

3. Proceed with creating new features

No Identifiable Features

If session has no clear feature work:

• Report: "No significant feature implementations detected in this session"
• Offer to manually describe what to document

Ambiguous Matches

When a session feature could match multiple existing specs:

• Present options to user
• Let them choose the correct match or create new

Integration with Other Skills

SPECLAN Format

Reference for proper file structure and frontmatter fields.

SPECLAN ID Generator

Use for collision-free ID generation.

Spec Converter

If user also has speckit, consider syncing there too.