land-delta

What this skill does

# Land Delta Workflow

Prepare a reconciled delta branch for merging into the project's main branch, reconciling any conflicts with changes introduced on main since the delta branched off.

## Input

Delta ID: $ARGUMENTS (e.g., "DLT-001")

If not provided, attempt to parse from the current branch name (look for `DLT-\d+` pattern). If not found, ask the user.

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles

### Feature documentation
- `docs/feature-specs/` - Long-lived feature specifications
- `docs/feature-designs/` - Long-lived feature designs

### Decision indexes
- `docs/architecture/README.md` - Architecture decisions (ADRs)
- `docs/design/README.md` - Design patterns (DES)

## Pre-Check

Run all checks before proceeding:

1. **Clean working tree**: `git status --porcelain` must be empty. If dirty, ask user to commit or stash.

2. **Not on main**: Current branch must not be the main branch. If on main, explain that this skill runs from the delta branch.

3. **Branch matches delta ID**: The current branch name should contain the delta ID (case-insensitive match, e.g., branch `dlt-042/feature-name` matches `DLT-042`). If mismatch, warn the user and ask to confirm before proceeding.

4. **Detect main branch**: Determine the main branch name:
   ```bash
   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
   ```
   If that fails, check for `main` or `master` branches. Ask user if ambiguous.

5. **Commits ahead of main**: Verify the branch has commits that main doesn't:
   ```bash
   git log origin/<main>..HEAD --oneline
   ```
   If no commits ahead, there's nothing to land.

6. **Delta reconciled**: Verify delta working documents have been cleaned up (reconciliation already happened):
   - Check that `docs/delta-specs/$ARGUMENTS.md` does NOT exist
   - Check that `docs/delta-designs/$ARGUMENTS.md` does NOT exist
   - Check that `docs/delta-plans/$ARGUMENTS.md` does NOT exist
   - If any exist, suggest running `/katachi:reconcile-delta $ARGUMENTS` first

## Scratchpad

Use `/tmp/land-$ARGUMENTS-state.md` for state tracking.

Track:
- Delta ID and branch name
- Main branch name
- Pre-rebase HEAD (backup reference)
- Original merge base (captured before rebase)
- Conflicts encountered (categorized by: code, feature-specs, feature-designs, decisions)
- Resolution decisions made
- Test/lint/typecheck results
- Documentation reconciliation notes
- Reviewer dispatch decisions and results

## Process

### Phase 1: Gather Context (Silent)

1. **Identify delta**: Resolve delta ID from `$ARGUMENTS`, branch name, or user prompt.

2. **Detect main branch**: Using the method from Pre-Check.

3. **Branch commit log**: Gather what the delta branch has done:
   ```bash
   git log origin/<main>..HEAD --oneline
   ```

4. **Read feature documentation**: Read current state of `docs/feature-specs/` and `docs/feature-designs/` on the branch to understand what the delta reconciled.

5. **Read decision indexes**: Read `docs/architecture/README.md` and `docs/design/README.md`.

6. **Fetch latest main**:
   ```bash
   git fetch origin <main>
   ```

7. **Capture pre-rebase references** (these MUST be captured before the rebase in Phase 2, as rebase rewrites HEAD's history and the original merge base relationship is lost):
   - **Pre-rebase HEAD**: `git rev-parse HEAD` — save to scratchpad as `$PRE_REBASE_HEAD` (safety backup in case rebase needs to be unwound)
   - **Original merge base**: `git merge-base HEAD origin/<main>` — save to scratchpad as `$ORIGINAL_BASE`
   - **Delta's own commits**: `git log $ORIGINAL_BASE..HEAD --oneline` — save to scratchpad as the delta summary
   - **Main's changes**: `git log $ORIGINAL_BASE..origin/<main> --oneline`
   - **Main's doc changes**: `git diff $ORIGINAL_BASE..origin/<main> -- docs/`
   Note which feature areas main changed, and whether new ADRs/DES were added.

### Phase 2: Rebase Delta Branch onto Main (Interactive)

Rebase the delta branch onto main to replay its commits on top of main's latest state:

```bash
git rebase origin/<main>
```

**Track conflict categories** — for each conflicting file encountered during the rebase, classify it:
- **Code**: Source code, tests, configuration files
- **Feature specs**: Files under `docs/feature-specs/`
- **Feature designs**: Files under `docs/feature-designs/`
- **Decisions**: Files under `docs/architecture/` or `docs/design/`

**If clean (no conflicts):**
- Proceed silently
- Note `conflicts_occurred = false` in scratchpad
- No reviewers will be dispatched in Phase 5

**If conflicts arise:**
- Note `conflicts_occurred = true` and record which categories had conflicts
- Rebase pauses at each conflicting commit. For each paused commit:
  - Read the conflict markers in the affected files
  - **Auto-resolve** simple conflicts:
    - Non-overlapping edits that git flagged conservatively
    - Whitespace or formatting-only changes
    - Import ordering differences
    - Additive changes from both sides (both added content to the same section)
  - **Ask the user** about complex conflicts:
    - Show what the delta commit changed vs what main changed
    - Explain the semantic meaning of each side
    - Present resolution options (accept delta's version, accept main's version, propose a merged version)
  - After resolving the current commit's conflicts:
    ```bash
    git add .
    git rebase --continue
    ```
  - If a commit's changes become empty after resolution (main already incorporated them):
    ```bash
    git rebase --skip
    ```

**If the same conflict recurs across multiple commits:**
- Note this in the scratchpad — it often indicates a commit sequence that would benefit from squashing before rebase
- Offer the user the option to abort and re-attempt with `git rebase -i origin/<main>` to squash related commits first

**If rebase becomes untenable:**
- Offer `git rebase --abort` to restore the pre-rebase state
- Discuss alternatives with the user (e.g., interactive rebase with squashing, or falling back to a merge approach)

### Phase 3: Code Reconciliation (Silent with checkpoint)

Ensure the branch passes all quality checks with zero failures before it can be landed. This is a clean-slate gate — fix everything, including issues that pre-date the delta or were already present on main:

1. **Run test suite**
2. **Run linting**
3. **Run type checking**

**If all pass:** Proceed silently.

**If failures:**
- Fix ALL failing tests, lints, and type errors — including pre-existing issues that were already on the branch or inherited from main. The landing is the gate: nothing with failing checks gets landed, regardless of when or where the failure was introduced.
- **Pay special attention to rebase-related semantic conflicts**: Failures caused by interactions between the delta's changes and main's changes are the highest priority. These may indicate deeper integration issues that need careful analysis (e.g., both sides changed related logic in incompatible ways, renamed references, changed APIs).
- **Auto-fix** straightforward issues:
  - Import path changes due to main's refactoring
  - Renamed references (functions, variables, types)
  - Minor API changes (added required parameters, changed return types)
  - Lint violations and formatting issues
  - Type errors with obvious fixes
  - Test failures with clear root causes
- **Ask the user** about issues that require judgment:
  - Semantic conflicts where the delta and main changed related behavior in incompatible ways
  - Ambiguous failures where the correct fix isn't obvious
  - Issues where fixing could change intended behavior
- Re-run checks after fixes until all pass

### Phase 4: Documentation Reconciliation (Silent with checkpoint)

Compare how both the delta and main changed documentation:

1. **Delta's documentation changes** (after rebase, delta's commits sit on top of main):