# Skill: Merge Executor

> Read the MERGE_PROMPT.md instruction file generated by the CLI, and merge each delta file from the change proposal into the main documents one by one, ensuring changes are applied accurately.

## Trigger Conditions

- User requests AI to execute the merge after running `openlogos merge <slug>`
- User mentions "execute merge", "merge", "merge the deltas into the main documents"
- User mentions "read MERGE_PROMPT.md and execute"

## Prerequisites

1. `logos/changes/<slug>/MERGE_PROMPT.md` exists (generated by the `openlogos merge` command)
2. The delta files and target main documents referenced in MERGE_PROMPT.md all exist

If MERGE_PROMPT.md does not exist, prompt the user to run `openlogos merge <slug>` first.

## Core Capabilities

1. Parse merge instructions from MERGE_PROMPT.md
2. Read each delta file and interpret ADDED / MODIFIED / REMOVED markers
3. Precisely locate the corresponding sections in the main document and execute the merge
4. Maintain formatting and style consistency of the main document
5. Output a change summary

## Execution Steps

### Step 1: Read Merge Instructions

Read `logos/changes/<slug>/MERGE_PROMPT.md` and parse:
- Change proposal name and overview
- Each delta file's path, corresponding target main document path, and operation type

### Step 2: Merge Each Delta File

Process delta files one by one in the order listed in MERGE_PROMPT.md:

1. **Read the delta file**: Understand the ADDED / MODIFIED / REMOVED markers and content
2. **Read the target main document**: Locate the sections that need modification
3. **Execute the merge**:
   - `ADDED`: Insert new content at the specified position in the main document
   - `MODIFIED`: Replace the content of the same-named section in the main document
   - `REMOVED`: Delete the corresponding section from the main document
4. **Output summary**: List what modifications were made to the file

### Step 3: Output Overall Change Report

After all deltas have been processed, output:

```
Merge complete:
- [file path 1]: added x sections, modified y sections, deleted z sections
- [file path 2]: ...
```

Then AI **automatically runs git commit** (no user confirmation needed, but must inform user):

```bash
git add -A
git commit -m "docs(<slug>): merge spec deltas"
```

> Use `git add -A` instead of `git add logos/resources/` to ensure all spec files touched by this merge (including spec/, skills/, CLAUDE.md, AGENTS.md, etc.) are included in the commit.

After the commit succeeds, write the spec-merged marker:

```bash
touch logos/changes/<slug>/SPEC_MERGED
```

`SPEC_MERGED` means the deltas have actually been merged into the main specs. `openlogos status` should enter the `coding` step only after this marker exists. `MERGE_PROMPT_GENERATED` / `MERGE_PROMPT.md` only means merge instructions were generated; it does not mean the main specs are already merged.

Then prompt the user with next steps:

```
✅ Spec documents merged and committed. Next steps:

Step 1: Implement code
Implement business code + test code per the updated logos/resources/ specs.
AI will automatically commit the code changes when done.

Step 2: Run verification (after code is complete)
Run in the project root:
openlogos verify
- PASS → proceed to Step 3
- FAIL → fix the code and re-run verify (no need to re-run merge)

Step 3: Archive (after verification passes)
openlogos archive <slug>

openlogos verify and openlogos archive are human confirmation points — AI must not execute them without explicit user authorization.
```

## Merge Principles

1. **Maintain format consistency**: Merged content must match the existing format, indentation, and heading levels of the main document
2. **Do not alter unrelated content**: Only modify the parts specified by the delta; do not reformat the entire document
3. **Ask on conflict**: If a section referenced by the delta cannot be found in the main document (possibly already modified by another change), pause and ask the user how to proceed
4. **Confirm after each file**: Show a modification summary after processing each delta file, and wait for user confirmation before processing the next one

## Output Specification

- Directly modify the main documents in `logos/resources/` (in-place editing)
- Do not modify files in `logos/changes/` except writing `logos/changes/<slug>/SPEC_MERGED`
- Do not create new files during the merge (unless a delta specifies adding a completely new document)

## Best Practices

- **Read everything before acting**: Read through all delta files and target documents first to understand the full picture, then merge one by one
- **MODIFIED is the most error-prone**: Section titles may have minor differences (capitalization, spacing) — fuzzy matching is needed
- **Preserve change traces**: If the main document has a "last updated" timestamp, remember to update it accordingly
- **Delta order matters**: Requirement document changes should be processed before API document changes to ensure upstream-downstream consistency

## Recommended Prompts

The following prompts can be copied directly for AI use:

- `Read logos/changes/<slug>/MERGE_PROMPT.md and execute the merge`
- `Help me merge the add-remember-me changes into the main documents`
- `Execute the change merge`