speckit-sync-backfill

name	speckit-sync-backfill
description	Generate a new spec from unspecced code feature (backfill)
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"sync:commands/backfill.md"}

Spec Sync: Backfill Spec

Generate a complete spec from an existing, unspecced code feature. Extracts intent from implementation, tests, and documentation.

User Input

$ARGUMENTS

The argument should be one of:

• A feature name (e.g., "reconciliation", "hints")
• A file path (e.g., "src/Fina.Cli/Commands/Register/RegisterReconcileCommand.cs")
• An identifier from the drift report (e.g., "unspecced-3")

Context

If a feature name is provided, search for relevant files:

• Commands with that name
• Services with that name
• Tests for that feature
• Any existing documentation

Steps

1. Discover Feature Scope

Find all files related to the feature:

# Commands
find src -name "*[Feature]*Command.cs" -o -name "*[Feature]*.cs"

# Services
find src -name "*[Feature]*Service.cs"

# Tests
find tests -name "*[Feature]*Tests.cs"

# Docs
find docs -name "*[feature]*"

2. Analyze Implementation

Read the discovered files and extract:

From Commands:

• Command name and description
• Options and arguments
• Validation rules
• Error handling

From Services:

• Public methods (these become requirements)
• Business logic rules
• Dependencies on other services
• Edge case handling

From Tests:

• Test scenarios (become acceptance scenarios)
• Expected behaviors
• Edge cases tested

From Existing Docs:

• Any informal documentation
• README sections
• Comments explaining "why"

3. Infer User Stories

From the command/service analysis, generate user stories:

### User Story 1 - [Primary Use Case] (Priority: P1)

As a user, I want to [action from main command]
so that [benefit inferred from feature purpose].

**Acceptance Scenarios**:

1. **Given** [precondition from tests], **When** [action], **Then** [expected result].

4. Extract Requirements

Convert implementation behaviors to requirements:

From method signatures:

public async Task<ReconcileResult> ReconcileAsync(string profileName, ...)

→ FR-001: System MUST support reconciliation per profile.

From validation:

if (!_authService.IsAuthenticated) throw ...

→ FR-002: System MUST validate authentication before reconciliation.

From business logic:

var matches = _fuzzyMatcher.FindMatches(transactions, registryRows, threshold: 0.85);

→ FR-003: System MUST use fuzzy matching with configurable threshold to match transactions.

5. Generate Spec Structure

Follow the standard spec template:

# Feature Specification: [Feature Name]

**Feature Branch**: `[spec-id]`
**Created**: [today's date]
**Status**: Backfilled
**Source**: Generated from existing implementation

## Backfill Notice

> ⚠️ This spec was generated from existing code via `speckit.sync.backfill`.
> It documents current behavior, not original intent.
> Review carefully and update to reflect desired behavior.

## User Scenarios & Testing

### User Story 1 - [Story] (Priority: P1)
[generated user story]

## Requirements

### Functional Requirements

- **FR-001**: [extracted requirement]
- **FR-002**: [extracted requirement]

### CLI Commands

- **FR-0XX**: System MUST provide `fina [command]` command...

## Key Entities

- **[Entity]**: [description from code]

## Dependencies

- **Spec [XXX]**: [dependency identified from imports/services]

## Success Criteria

- **SC-001**: [derived from tests or obvious metrics]

## Implementation Notes

> These notes capture current implementation details that may or may not
> belong in the spec long-term.

- [implementation detail 1]
- [implementation detail 2]

6. Determine Spec ID

Find the next available spec number:

ls specs/ | grep -E '^[0-9]+' | sort -n | tail -1

Suggest: {next_number}-{feature-name}

7. Generate Plan

Create plan.md documenting the implementation architecture:

# Implementation Plan: [Feature Name]

**Branch**: `[spec-id]` | **Date**: [today] | **Spec**: [spec.md](spec.md)
**Context**: Backfilled from existing implementation. Documents current architecture.

## Summary

[Brief description of what the feature does]

## Technical Context

**Language/Version**: [detected from project]
**Primary Dependencies**:
- [Service 1] — [purpose]
- [Service 2] — [purpose]

**Performance Goals**: [if identifiable from code/tests]

## Architecture

### Service Layer

[Main Service] ├── [Dependency 1] ├── [Dependency 2] └── [Dependency 3]

### Flow

1. [Step 1]
2. [Step 2]
3. [Step 3]

### Key Design Decisions

1. **[Decision 1]**: [rationale from code/comments]
2. **[Decision 2]**: [rationale]

## Project Structure

```text
src/[paths discovered]
tests/[paths discovered]

Dependencies

• Spec [XXX]: [dependency]

Testing

[Test file locations]

Future Considerations

[Any TODOs or comments suggesting future work]

### 8. Generate Quickstart

For user-facing features (CLI commands), create `quickstart.md`:

```markdown
# Quickstart: [Feature Name]

[One-line description of what users can do]

## Prerequisites

1. [Prerequisite 1]
2. [Prerequisite 2]

## Basic Usage

```bash
# [Primary use case]
fina [command] [args]

Options

Option	Description
--option1	[description]
--option2	[description]

Examples

[Use case 1]

fina [command] [example]

[Use case 2]

fina [command] [example]

Tips

• [Tip 1]
• [Tip 2]

Skip `quickstart.md` for internal/non-user-facing features.

### 9. Output Options

**Preview Mode (default):**
Display generated spec, plan, quickstart, and tasks for review.

**Create Mode (`--create`):**
1. Create `specs/{id}/spec.md`
2. Create `specs/{id}/plan.md`
3. Create `specs/{id}/quickstart.md` (if user-facing)
4. Create `specs/{id}/tasks.md` (with review task)
5. Report location

### 10. Generate Review Task

Add a task to review the backfilled spec:

```markdown
# Tasks

## Review Backfilled Spec

- [ ] Review generated user stories for accuracy
- [ ] Verify requirements match intended behavior (not just current behavior)
- [ ] Remove implementation notes that don't belong in spec
- [ ] Add any missing requirements
- [ ] Mark spec status as "Draft" or "Approved"

Example Usage

/speckit.sync.backfill reconciliation

/speckit.sync.backfill src/Fina.App/Services/Reconciliation/ReconciliationService.cs

/speckit.sync.backfill reconciliation --create

/speckit.sync.backfill hints --spec-id 014

Notes

• Backfilled specs should always be reviewed by a human
• The spec documents current behavior, which may include bugs
• Use this as a starting point, not a final spec
• Consider whether the feature should be split into multiple specs
• plan.md documents architecture decisions; useful for onboarding and future changes
• quickstart.md is user documentation; skip for internal-only features