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