### Workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Explore the feature
- [ ] Step 2: Merge design docs
- [ ] Step 3: Merge implementation docs
- [ ] Step 4: Generate task list
- [ ] Step 5: Final review
```

**Inputs:** Two feature directories under `/docs/feat/wip/` (e.g., `auth-system-v1/` and `auth-system-v2/`).

**Output:** A new directory `/docs/feat/wip/[feature-title]-merged/` containing the unified `design.md`, `implementation.md`, and `tasks.md`.

---

**Step 1: Explore the feature**

Before you can judge which doc is more correct, you need to understand what we're actually building.

- Read both feature directories fully — design, implementation, and tasks from each
- Explore the codebase: relevant source files, existing architecture, patterns in use
- Check contributing guidelines, relevant documentation, and any prior art
- Build a mental model of the feature's purpose, constraints, and integration points

You cannot make good merge decisions without this grounding. Don't skip it. Make sure you have a very thorough understanding of both the existing state and the new feature.

**Capy search:** Before merging, search `kk:arch-decisions` for prior decisions relevant to the competing approaches.

**Step 2: Merge design docs**

Read both design docs and categorize every section/decision into one of four buckets:

| Category          | What it means                                               | Action                                                                                                                                                |
| ----------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agreement**     | Both docs say the same thing                                | Keep as-is — use whichever framing is clearer                                                                                                         |
| **Gap**           | One doc covers something the other doesn't                  | Verify against codebase reality (re-read the codebase if needed). If correct, merge in. If wrong, drop with explanation                               |
| **Contradiction** | Both docs cover the same topic but disagree                 | Surface to user for resolution — one question at a time                                                                                               |
| **Error**         | A doc claims something that conflicts with codebase reality | Verify against codebase reality (re-read the codebase if needed). Assign confidence percentage. Flag to user, recommend keeping/dropping, explain why |

**How to surface decisions to the user:**

- Resolve agreements and straightforward gaps silently
- For each contradiction or judgment call, present it as a single question with:
  - What Doc A says
  - What Doc B says
  - Your recommendation (grounded in what you learned in Step 1) and why
  - Ask the user to pick or provide an alternative
- One question per message. Wait for a response before moving on.

After all decisions are made, write the merged `design.md` to `/docs/feat/wip/[feature-title]-merged/`.

**Step 3: Merge implementation docs**

This step is informed by two things:

1. Your understanding of the codebase (from Step 1)
2. The decisions already made in the merged design (from Step 2)

Do NOT treat this as a blind semantic comparison of the two original implementation docs. If the merged design changed direction on something, the implementation merge must reflect that — even if both original implementation docs agreed on the old direction.

Apply the same four-bucket categorization (agreement, gap, contradiction, error), but also check each section against the merged design:

- Does this implementation section still align with the merged design? If not, flag it.
- Did the design merge introduce new decisions that need implementation coverage? If so, add them.
- Did the design merge drop something? Remove the corresponding implementation sections.

Surface contradictions and judgment calls to the user the same way as in Step 2.

Write the merged `implementation.md` to `/docs/feat/wip/[feature-title]-merged/`.

**Step 4: Generate task list**

The task list is a **derived artifact** — generate it from the merged implementation plan, don't merge the two original task lists directly.

1. Read the merged `implementation.md` and break it into tasks following the same structure and conventions as the [design example tasks](../design/example-tasks.md)
2. For each new task, check if a corresponding task exists in either original `tasks.md`:
   - If a matching task exists and is `done` or `in-progress`, carry forward its status and subtask completion — but update the subtask descriptions if the merged implementation changed the details
   - If a matching task exists but the implementation changed significantly, reset to `pending` with updated subtasks
   - If no matching task exists (new section from the merge), create a fresh `pending` task
3. Preserve dependency ordering based on the merged implementation plan
4. Include a final verification task (same pattern as design)

Write `tasks.md` to `/docs/feat/wip/[feature-title]-merged/`.

**Step 5: Final review**

Present the user with a summary of the merged output:

- List of key decisions made (both silent resolutions and user-guided ones)
- Sections where the merge significantly diverged from either original
- Any open concerns or areas that may need further refinement
- Links to the three output files

Ask the user to review and confirm, or flag anything that needs adjustment.

**Capy index:** If the merge resolved a genuine architectural conflict, index the resolution rationale as `kk:arch-decisions`.

# Capy Knowledge Base Protocol

If `capy` MCP tools are not available in this session, skip all search and index steps below and proceed normally.

## Source Label Taxonomy

All plugin-managed labels use the `kk:` namespace prefix.

| Label                    | Contents                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| `kk:arch-decisions`      | Architecture decisions, design rationale, trade-offs                  |
| `kk:review-findings`     | Code review patterns, recurring issues, anti-patterns                 |
| `kk:lang-idioms`         | Language best practices, idiomatic patterns from external sources     |
| `kk:project-conventions` | Discovered project patterns, naming conventions, structural decisions |
| `kk:test-patterns`       | Testing approaches, edge cases, test infrastructure decisions         |
| `kk:debug-context`       | Root causes, tricky bugs and their fixes, environment gotchas         |

## Search Conventions

- Use 2-4 specific terms per query — not vague keywords
- Always scope with `source` filter to relevant `kk:*` labels
- Use `source: "kk:"` only for broad cross-domain searches (e.g., CoVe verification)
- Default `limit: 3` per query unless more context is needed
- **Cold-start fallback:** If no results, proceed with standard guidelines — empty results are normal for new projects

## Index Conventions

- Only index non-obvious learnings not derivable from reading the code or git history
- Keep content concise — summarize the insight, don't dump raw output
- Always use a `kk:` prefixed label from the taxonomy above
- One concept per `capy_index` call — don't bundle unrelated learnings
- Skip indexing if the insight is already captured in design docs or CLAUDE.md

---
name: merge-docs
description: |
  Compare and merge two design docs for the same feature into a single source of truth.
  Use when you have competing or complementary design/implementation docs (e.g. from separate design runs) that need reconciling into one unified document.
---
<!-- codex: tool-name mapping applied. See .codex/scripts/session-start.sh -->

# Merge Design Documents

**Goal: Produce a single, unified set of feature docs from two separate designs for the same feature.**

## Conventions

- **Read capy knowledge base conventions** at [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md).

## When to Use

You have two feature directories under `/docs/feat/wip/` for the same feature — each with its own design, implementation plan, and task list — and you need to combine them into one coherent set of docs.

## Workflow

**Mandatory order — grounding before merging.** The flow below is strictly sequential. Do not categorize sections, surface contradictions, or write merged content until you have read both feature directories fully and built a codebase-grounded mental model. Merging without grounding produces decisions based on prose clarity rather than codebase reality — the wrong tiebreaker.

See [merge-process.md](./merge-process.md) for the detailed steps.