speckit-sync-propose

name	speckit-sync-propose
description	Propose resolutions for detected drift. AI generates spec updates or code changes.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"sync:commands/propose.md"}

Spec Sync: Propose Resolutions

Generate resolution proposals for each drift item. The AI analyzes each divergence and proposes either a spec update (backfill) or code change (align).

User Input

$ARGUMENTS

Prerequisites

Run speckit.sync.analyze first to generate the drift report.

Context

Read the drift report:

• .specify/sync/drift-report.json

Steps

1. Load Drift Report

Read the drift report from the previous analysis. If it doesn't exist, instruct the user to run speckit.sync.analyze first.

2. For Each Drifted Requirement

Analyze the drift and determine resolution direction:

Backfill (Code → Spec)

Recommend when:

• Code has working, tested features not in spec
• Design docs exist that supersede the spec
• The code represents intentional evolution
• Tests pass for the current behavior

Generate:

• Updated spec requirement text
• New acceptance scenarios if needed
• Rationale for why code is authoritative

Align (Spec → Code)

Recommend when:

• Spec was recently reviewed/approved
• Code appears to be a bug or misunderstanding
• The spec represents agreed architectural decisions
• Changing the spec would violate constraints

Generate:

• Code change description or diff
• Task for implementation
• Rationale for why spec is authoritative

Human Decision Required

Flag when:

• Both interpretations seem valid
• Architectural trade-offs involved
• Insufficient context to decide
• Conflicting design documents

Generate:

• Summary of both options
• Questions that would help decide
• Request for human input

3. For Each Unspecced Feature

Propose a new spec:

• Suggested spec ID (next available number)
• Draft title
• Draft user stories based on code behavior
• Draft requirements extracted from implementation
• Confidence score

4. For Each Not-Implemented Requirement

Determine:

• Is it still needed? (may be obsolete)
• Should it be removed from spec?
• Should it be implemented?

Propose accordingly.

5. Generate Proposal Document

Output format:

# Drift Resolution Proposals

Generated: [timestamp]
Based on: drift-report from [timestamp]

## Summary

| Resolution Type | Count |
|-----------------|-------|
| Backfill (Code → Spec) | X |
| Align (Spec → Code) | X |
| Human Decision | X |
| New Specs | X |
| Remove from Spec | X |

## Proposals

### Proposal 1: [spec-id]/[requirement]

**Direction**: BACKFILL | ALIGN | HUMAN_DECISION

**Current State**:
- Spec says: "[spec text]"
- Code does: "[actual behavior]"

**Proposed Resolution**:

[For BACKFILL: new spec text]
[For ALIGN: code change description]
[For HUMAN: questions and options]

**Rationale**: [why this direction]

**Confidence**: HIGH | MEDIUM | LOW

**Action**:
- [ ] Approve
- [ ] Reject
- [ ] Modify

---

### Proposal 2: New Spec for [feature]

**Direction**: NEW_SPEC

**Feature**: [feature name]
**Location**: [code path]

**Draft Spec**:

# Feature Specification: [title]

## User Scenarios

### User Story 1 - [story]
[generated from code behavior]

## Requirements

- **FR-001**: [extracted from code]

**Confidence**: MEDIUM

**Action**:
- [ ] Approve and create spec
- [ ] Reject
- [ ] Modify

6. Save Proposals

Write to:

• .specify/sync/proposals.md (human-readable)
• .specify/sync/proposals.json (machine-readable)

Interactive Mode

When run with --interactive, present each proposal one at a time and prompt for approval:

Proposal 1/15: spec-011/FR-001

Direction: BACKFILL (Code → Spec)

Spec says: "one row per document"
Code does: "supports split transactions with multiple rows"

Proposed update:
  - FR-001: System MUST append one or more rows per extracted document.
            For split transactions, multiple rows share a LinkID.

Confidence: HIGH

[A]pprove / [R]eject / [M]odify / [S]kip / [Q]uit?

Example Usage

/speckit.sync.propose

/speckit.sync.propose --interactive

/speckit.sync.propose --strategy backfill-all