intent-sync

Intent Sync

Synchronize implementation details back to Intent after development is complete. This makes Intent the true single source of truth.

When to Use

Use /intent-sync when:

• Implementation is complete
• All tests pass
• User has confirmed the implementation works
• You want to capture the finalized design in Intent

What Gets Synced Back

During implementation, many details get finalized that weren't specified in the original Intent:

Category	Examples
Interfaces	API endpoints, function signatures, protocol definitions
Data Structures	Schema definitions, type definitions, model structures
Naming	Final class names, function names, variable conventions
Architecture	Module boundaries, dependency directions, layer structure
Configuration	Environment variables, config file formats, defaults
Error Handling	Error codes, error message formats, recovery strategies

Workflow

User confirms implementation is done
    ↓
Read original Intent file
    ↓
Scan implemented code for:
    - Public interfaces
    - Data structures
    - Key naming conventions
    - Architecture patterns
    ↓
Compare with Intent
    ↓
Identify gaps/differences
    ↓
Present changes for approval
    ↓
Update Intent with confirmed details
    ↓
Mark synced sections with timestamp

Sync Process

Step 1: Gather Implementation Facts

Scan the codebase for finalized details:

Code Analysis:
├── Public APIs
│   ├── Endpoints (REST/GraphQL/RPC)
│   ├── Function signatures
│   └── Event definitions
├── Data Models
│   ├── Database schemas
│   ├── Type definitions
│   └── Config structures
├── Architecture
│   ├── Module structure
│   ├── Dependency graph
│   └── Layer boundaries
└── Conventions
    ├── Naming patterns
    ├── Error formats
    └── Logging standards

Step 2: Compare with Intent

Identify what's new or different:

Status	Meaning	Action
New	Not in original Intent	Add to Intent
Changed	Different from Intent	Update Intent
Confirmed	Matches Intent	Mark as implemented
Removed	In Intent but not implemented	Remove or mark deferred

Step 3: Present for Approval

Use AskUserQuestion to confirm changes:

"The following details were finalized during implementation.
Should I sync them back to Intent?"

Interfaces:
- [x] POST /api/users - Create user (new)
- [x] UserSchema: added 'createdAt' field (changed)

Data Structures:
- [x] Config now uses YAML instead of JSON (changed)

Naming:
- [x] Service class renamed to UserService (changed)

Step 4: Update Intent

Add a new section or update existing sections:

## Finalized Implementation Details

> Synced on: YYYY-MM-DD
> From: [commit hash or version]

### API Interfaces

| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| /api/users | POST | `{name, email}` | `{id, name, email, createdAt}` |
| /api/users/:id | GET | - | `{id, name, email, createdAt}` |

### Data Structures

\`\`\`typescript
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}
\`\`\`

### Module Structure

\`\`\`
src/
├── api/
│   └── users.ts       # User endpoints
├── services/
│   └── UserService.ts # Business logic
├── models/
│   └── User.ts        # Data model
└── config/
    └── config.yaml    # Configuration
\`\`\`

### Key Decisions Confirmed

| Decision | Final Choice | Rationale |
|----------|--------------|-----------|
| Config format | YAML | Better readability for nested config |
| ID generation | UUID v4 | Standard, no coordination needed |

Output Format

The sync adds or updates these Intent sections:

New Section: ## Finalized Implementation Details

Contains:

• Sync timestamp
• Source reference (commit/version)
• Concrete interfaces
• Concrete data structures
• Final module structure
• Confirmed decisions

Updated Existing Sections

• Architecture diagrams updated to reflect reality
• Data contracts updated with actual schemas
• API specifications updated with real endpoints

Sync Markers

Use markers to indicate sync status:

## API Design

> [!SYNCED] Last synced: 2024-01-15 from commit abc123

### Endpoints
...

Or in tables:

Component	Status	Last Synced
User API	SYNCED	2024-01-15
Auth API	DRAFT	-

Integration with Other Skills

/intent-interview     # Create Intent (initial)
    ↓
/intent-review        # Approve Intent
    ↓
/intent-plan          # Generate execution plan
    ↓
[Execute: TDD cycles]
    ↓
/intent-sync          # Write back confirmed details (THIS SKILL)
    ↓
/intent-check         # Verify consistency

Best Practices

1. Sync after stability: Don't sync during active development; wait for confirmation
2. Preserve original intent: Keep original design rationale, add implementation details
3. Be specific: Include actual types, actual endpoints, actual names
4. Version reference: Always note which code version was synced
5. Incremental sync: Can sync multiple times as features stabilize

Example Session

User: Implementation is done, tests pass. Please sync back to Intent.