Land Delta

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:

   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:

   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:

   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:

   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:

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:

    git add .
    git rebase --continue
    

  • If a commit's changes become empty after resolution (main already incorporated them):

    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):

   git diff origin/<main>..HEAD -- docs/feature-specs/ docs/feature-designs/
   

2. Main's documentation changes (use original base captured in Phase 1):

   git diff $ORIGINAL_BASE..origin/<main> -- docs/feature-specs/ docs/feature-designs/ docs/architecture/ docs/design/
   

Check for:

1. Same feature docs modified by both: Semantic conflicts in feature specs or designs where both sides changed the same sections with different intent.

2. New ADRs/DES on main: Check if main added ADRs or DES patterns that weren't present when the delta was being worked on. Cross-reference against the delta's feature area.

3. Feature docs deleted on main: If main deleted feature docs that the delta updated, the rebase would have surfaced this as a conflict. If not caught during rebase, note as informational.

4. New feature docs on main: Check for overlap with the delta's reconciled documentation.

If no issues: Proceed silently.

If issues found:

• Auto-fix non-conflicting doc updates (additive changes from both sides, formatting adjustments)
• Ask the user about:
  • Semantic conflicts: present both sides with context, offer merge options
  • New ADRs/DES on main that affect the delta's feature area: present them, ask if the delta's code or docs need adjustment to comply
  • Contradictions between main's changes and the delta's documentation

Phase 5: Targeted Validation (Silent, only if conflicts occurred)

Skip this phase entirely if conflicts_occurred = false — the delta was already validated during implementation and reconciliation, and a clean rebase means no integration risks.

If conflicts occurred, dispatch only the reviewers relevant to the conflicting categories. Run applicable reviewers in parallel.

Code review (only if code files had conflicts):

Task(
    subagent_type="katachi:code-reviewer",
    prompt=f"""
Review this delta's code after rebasing onto main.
Focus specifically on INTEGRATION concerns:

## Delta Summary
{delta_summary_from_commits}

## Changes introduced by main since delta branched
{main_changes_summary}

## Rebase conflict files and resolutions
{conflict_resolutions}

## Current code diff (delta vs main after rebase)
{code_diff}

## Relevant ADR/DES Documents
{adr_des_content}

Focus on:
- Semantic conflicts (code compiles but behaves incorrectly)
- Pattern compliance with any new ADRs/DES added on main
- Integration issues between delta changes and main changes
- Do NOT review the delta's implementation quality (already reviewed)
"""
)

Spec review (only if feature-specs had conflicts):

Task(
    subagent_type="katachi:spec-reviewer",
    prompt=f"""
Review feature specs after rebasing delta branch onto main.

## Delta Summary
{delta_summary_from_commits}

## Feature Spec Changes (delta's reconciled updates)
{delta_spec_changes}

## Feature Spec Changes from Main
{main_spec_changes}

## Reconciled Feature Specs (current state)
{current_feature_specs}

Verify that reconciled feature specs:
- Remain internally consistent after incorporating both sets of changes
- Acceptance criteria don't contradict each other
- User stories are coherent
"""
)

Design review (only if feature-designs had conflicts):

Task(
    subagent_type="katachi:design-reviewer",
    prompt=f"""
Review feature designs after rebasing delta branch onto main.

## Delta Summary
{delta_summary_from_commits}

## Feature Design Changes (delta's reconciled updates)
{delta_design_changes}

## Feature Design Changes from Main
{main_design_changes}

## Reconciled Feature Designs (current state)
{current_feature_designs}

## ADR Index
{adr_index}

## DES Index
{des_index}

Verify that reconciled feature designs:
- Maintain design coherence after incorporating both sets of changes
- Properly reference all relevant ADRs/DES (including any new ones from main)
- Component interactions remain consistent
"""
)

Decision review (only if decision docs had conflicts):

Task(
    subagent_type="katachi:decision-reviewer",
    prompt=f"""
Review decision consistency after rebasing delta branch onto main.

## Delta Summary
{delta_summary_from_commits}

## New ADRs Added on Main
{new_adrs_from_main}

## New DES Added on Main
{new_des_from_main}

## Delta's Implementation Approach
{delta_implementation_summary}

## Existing ADR Index
{adr_index}

## Existing DES Index
{des_index}

Check for:
- New decisions from main that the delta's code doesn't comply with
- Contradictions between delta decisions and new main decisions
- Patterns that should be documented as DES given both sets of changes
"""
)

After all dispatched reviewers return:

• Auto-fix all issues found
• Run full test/lint/typecheck suite one final time — all must pass with zero failures
• If issues remain after fixes: present to user with context and discuss — do NOT proceed to Phase 6 until all checks pass

Phase 6: Summary

Present the ready-to-land summary, including a reminder about force-pushing since rebase rewrites history:

"DLT-XXX is ready to merge into <main>.

Rebase onto main: [Clean / Resolved N conflicts across M commits]
Checks: [All passing (zero failures) / Fixed N issues to reach zero failures (brief description)]
Documentation: [Consistent / Reconciled N files]
Validation: [Passed / Skipped (no conflicts)]

Note: this branch was rebased. If it was previously pushed, you'll need to force-push with lease:
  git push --force-with-lease origin <branch-name>"

Edge Cases

No conflicts (clean rebase): Skip Phase 2 conflict resolution AND Phase 5 validation. Still run Phases 3-4 (code/doc reconciliation) since semantic issues can exist without rebase conflicts.

Rebase conflicts that can't be auto-resolved: Present conflict context with both sides explained. Offer options: resolve manually, accept ours/theirs, skip the commit if already incorporated on main, or abort the rebase entirely with git rebase --abort.

Same conflict recurring across commits: Indicates a commit history that would benefit from squashing. Offer to abort and re-attempt with git rebase -i origin/<main> to consolidate related commits before replaying.

Working tree is dirty: Pre-check catches this. Ask user to commit or stash before proceeding.

Delta not yet reconciled: Detected by presence of delta working documents (docs/delta-specs/<ID>.md, etc.). Suggest running /katachi:reconcile-delta $ARGUMENTS first.

New decisions on main contradict delta decisions: Present both the new decision and the delta's approach in Phase 4. Ask user how to proceed: update delta code to comply, update the decision document, or note the exception.

Multiple deltas on same branch: Ask user which delta to focus on. The code/doc reconciliation works the same regardless of which delta ID is specified — the rebase replays all commits on the branch.

Branch name doesn't match delta ID: Pre-check warns the user and asks for confirmation. The user may have a valid reason (e.g., renamed branch, or branch covers multiple deltas).

Branch was previously pushed: Rebase rewrites history, so a subsequent push requires --force-with-lease. The Phase 6 summary reminds the user. Never force-push on behalf of the user without explicit confirmation.

Workflow

This is a rebase-reconcile-validate process:

• Pre-check (clean tree, correct branch, reconciled delta)
• Gather context (branch commits, main changes, feature docs, decisions) and capture pre-rebase references
• Rebase branch onto main (resolve conflicts interactively, per commit)
• Code reconciliation (tests, lint, typecheck — auto-fix or ask)
• Documentation reconciliation (semantic doc conflicts — auto-fix or ask)
• Targeted validation (only conflicting categories get reviewed)
• Present ready-to-land summary (including force-push reminder)