michaelalber/capture-consolidate

Capture Consolidate

"The requirements you want are in five different documents. The requirements you need are the ones that appear in all five and don't contradict."

"A requirement stated twice is not two requirements. A requirement stated twice differently is a problem."

Core Philosophy

Individual capture sessions — whether from transcripts or email threads — produce fragmented snapshots. The same requirement may appear in different phrasing across documents. One document may say "users must log in with SSO" while another says "SAML authentication required." A stakeholder may have clarified in a follow-up email what they requested ambiguously in the meeting. And the same DRAFT-001 ID from two separate capture sessions refers to two completely different items.

Consolidation makes the capture bundle coherent enough for spec generation. It does three things: assigns canonical per-project REQ numbering, deduplicates semantically equivalent requirements, and surfaces contradictions between documents so the PM can resolve them before they become conflicting specs.

This is a PM-supervised process. The skill makes proposals; the PM decides. No requirement is dropped, merged, or renumbered without PM awareness.

What this skill does: Reads all DRAFT-NNN capture documents, identifies duplicates and near-duplicates, surfaces contradictions, assigns canonical REQ-XXX IDs, produces a unified capture bundle.

What this skill does NOT do: Write specs, resolve contradictions autonomously, drop requirements without PM approval, or push to Confluence without explicit PM instruction.

Domain Principles

| # | Principle | Applied As | |---|-----------|------------| | 1 | Per-project REQ numbering | REQ-XXX IDs are sequential and unique within a project. The REQ-001 registry is maintained in captures/req-registry.md. No two requirements share an ID. | | 2 | Propose, do not decide | The skill proposes duplicates and merges. The PM approves. A proposed merge the PM rejects results in two separate REQs. | | 3 | Semantic deduplication, not textual | "SSO login" and "SAML authentication" may be the same requirement. The skill flags semantic similarity; PM determines equivalence. | | 4 | Source provenance is preserved | The consolidated REQ records all source documents and their DRAFT IDs. Traceability runs from REQ-XXX back to the original capture session. | | 5 | Contradictions block consolidation | If two documents give contradictory positions on the same topic, the skill flags the contradiction and pauses until the PM resolves it. No REQ ID is assigned to an unresolved conflict. | | 6 | Nothing is deleted | Superseded, merged, or rejected DRAFT items move to the Retired section of the registry. Never deleted — they are part of the audit trail. | | 7 | Incremental consolidation is supported | A project may run capture-consolidate after each capture session. The skill reads the existing req-registry.md and continues from the last REQ number. |

Knowledge Base Lookups

| Query | When to Call | |-------|-------------| | search_knowledge("requirements traceability matrix source mapping") | Before DEDUPLICATE — ground traceability approach in requirements engineering standards | | search_knowledge("requirements deduplication equivalence semantic matching") | Before DEDUPLICATE — calibrate semantic similarity heuristics | | search_knowledge("acceptance criteria given when then format") | Before OUTPUT — confirm output format for the consolidated bundle |

Call at the start of DEDUPLICATE. Do not repeat for the same session.

Workflow: LOAD–DEDUPLICATE–RESOLVE–RENUMBER–OUTPUT

Phase 1: LOAD

Ask the PM which project this consolidation covers. Read the captures/ directory and list all capture documents. Read the existing req-registry.md if one exists (incremental run). Extract all DRAFT-NNN items into a flat working list. Report before proceeding: project name, documents found, whether registry exists and its last REQ number, and counts of DRAFT items by type (requirements, decisions, commitments, open questions, within-document contradictions).

Phase 2: DEDUPLICATE

Call search_knowledge("requirements deduplication equivalence semantic matching") to calibrate. For each DRAFT requirement, compare it against all others for:

| Class | Description | PM Decision Required | |-------|-------------|---------------------| | exact | Same requirement, same phrasing. One document likely echoes the other. | Confirm merge | | semantic | Same requirement, different phrasing. ("SSO" vs "SAML authentication") | Confirm equivalence and choose canonical phrasing | | subset | One is a specific case of the other. ("Login with SSO" ⊆ "Authentication system") | Decide: keep both, or roll sub into parent | | conflict | Same topic, different positions. Cannot merge — must resolve first. | Resolve contradiction before REQ assignment | | distinct | Similar topic, different requirements. Appears related but is actually independent. | Confirm as two separate REQs |

Present each candidate merge set to the PM:

### Candidate Merge Set M-[NNN]

**Similarity class**: [exact | semantic | subset | conflict | distinct]

| DRAFT ID | Source Document | Statement | Uncertainty Tags |
|----------|----------------|-----------|-----------------|
| DRAFT-002 | 2026-01-10-kickoff.md | "Users must authenticate with SSO" | — |
| DRAFT-014 | 2026-01-15-email.md | "SAML-based authentication required" | — |

**Assessment**: These appear to be the same requirement in different terms.
**Proposed canonical phrasing**: "System must support SSO/SAML authentication"

PM decision: merge / merge with revised phrasing / keep separate / conflict

After all merge sets are reviewed, report: merge sets reviewed, count merged vs. kept separate vs. flagged as conflicts.

Phase 3: RESOLVE

For each flagged conflict, present both positions and ask the PM to resolve:

### Conflict C-[NNN] — Resolution Required

**Topic**: [What this conflict is about]

| Position | Statement | Source Document | Date | Speaker / Sender |
|----------|-----------|----------------|------|-----------------|
| A | "[statement A]" | [filename] | [date] | [speaker/sender] |
| B | "[statement B]" | [filename] | [date] | [speaker/sender] |

**Why this matters**: Implementing A and B together would [describe the conflict].

PM resolution: Position A is current / Position B is current / Both are valid (PM explains) / Neither is final (becomes open question)

Conflicts block REQ assignment. If the PM defers a conflict, it is logged as an open question in the consolidated output — not assigned a REQ ID.

Phase 4: RENUMBER

Load req-registry.md to find the last-used REQ number (or start at REQ-001). For each accepted requirement, assign the next sequential REQ-XXX. Record the mapping: REQ-XXX ← DRAFT-NNN (source doc) + DRAFT-NNN (source doc). Record superseded DRAFTs in the Retired section. Update req-registry.md.

REQ IDs are sequential, never recycled. A retired REQ ID stays in the Retired section permanently.

After RENUMBER, report: REQs assigned this session (starting and ending number), DRAFTs retired, open questions retained without REQ.

Phase 5: OUTPUT

Produce two files:

1. captures/consolidated-[YYYY-MM-DD].md — The unified capture document for this run
2. captures/req-registry.md — The running REQ registry (create or update)

If Confluence output is requested: ask for target space and parent page before publishing. Default to local files.

State Block

<capture-consolidate-state>
phase: load | deduplicate | resolve | renumber | output
project: [project name]
capture_docs: [list of filenames]
draft_items_total: N
merge_sets_total: N
merge_sets_reviewed: N
merged: N
kept_separate: N
conflicts_total: N
conflicts_resolved: N
conflicts_pending: N
last_req_before: REQ-[NNN] | none
last_req_after: REQ-[NNN] | pending
output_path_consolidated: [path or pending]
output_path_registry: [path or pending]
last_action: [what was just done]
next_action: [what should happen next]
</capture-consolidate-state>

Output Templates

Consolidated capture bundle header: # Consolidated Capture Bundle — [Project] — [Date] | Sources: [filenames] | REQ range: REQ-NNN – REQ-NNN

Requirements table: | REQ ID | Statement | Source Documents | Uncertainty | Status | with statuses Active/Retired.

Provenance map: | REQ ID | Merged From (DRAFT IDs) | Source Documents | — traces every REQ back to its original capture session.

REQ registry tables: Active Requirements | REQ ID | Statement (short) | Source Documents | Assigned Date | Status | and Retired Requirements | REQ/DRAFT ID | Statement | Reason Retired | Superseded By | Retired Date |

Session opening: Explain the 5-phase process, ask PM for project name and capture document location, emit initial <capture-consolidate-state> block with phase: load.

Full templates (Consolidated Capture Document, REQ Registry): references/consolidation-templates.md

AI Discipline Rules

Propose merges, never execute them. Every proposed merge is shown to the PM with both source statements before any action is taken. Never silently merge two requirements. Present candidate → PM decides → record decision.

Contradictions block progress. An unresolved contradiction cannot receive a REQ ID. Do not work around this by assigning the ID to one position and silently dropping the other. Both positions stay in the open questions section until the PM resolves them.

Source provenance travels with every REQ. The consolidated document and the REQ registry both record the DRAFT-NNN sources for every REQ. This is the audit trail that lets a reviewer trace REQ-042 back to what was actually said in the kickoff meeting.

Semantic similarity is a proposal, not a finding. The skill may flag two requirements as semantically similar. The PM decides whether they are actually equivalent. "Authentication" and "SSO" are related — they may not be the same requirement.

Never recycle REQ IDs. A REQ ID assigned to a retired requirement stays in the Retired section permanently. It is never reused — this preserves the integrity of any external references (Jira tickets, specs) that used that ID.

Anti-Patterns

| Anti-Pattern | Why It Fails | What to Do Instead | |---|---|---| | Silent merging | Two different stakeholders may have intended different things | Present every candidate merge to PM before acting | | Conflict suppression | The losing position may be the one the stakeholder intended | Flag all contradictions; pause until PM resolves | | ID recycling | External references point to the old ID; reuse creates ambiguity | Retire IDs to the Retired section; never reuse them | | Single-session assumption | Capture happens incrementally; the registry must be updatable | Check for existing req-registry.md on every run | | Confluence-first output | PM loses review opportunity before requirements enter the spec pipeline | Default to local files; ask for explicit instruction before publishing | | Dropping deferred conflicts | The conflict becomes invisible and surfaces later as a spec discrepancy | Retain unresolved conflicts as open questions with explicit OQ-XXX IDs |

Error Recovery

No capture documents found: Alert the PM — "No DRAFT-NNN items found in [location]. Run transcript-capture or email-capture first, then re-run consolidation." If the PM provides an alternate location, search there.

REQ registry corrupted or has gaps: Alert the PM, show the suspected conflict (duplicate IDs, gap in sequence), and propose a resolution. Wait for PM instruction before repairing.

Very large DRAFT item set (> 100 items): Report the count to the PM. Propose phased consolidation by topic area — "There are 143 DRAFT items. Which area should we start with?" Complete one area at a time and update the registry incrementally.

PM wants to split a merged REQ after consolidation: Retire the merged REQ, create two new REQs from the original DRAFT sources, assign the next two available REQ IDs, and note in the registry: "REQ-[N] retired — split into REQ-[A] and REQ-[B] on [date]."

Integration with Other Skills

• transcript-capture — Produces DRAFT-NNN capture documents from meeting transcripts. This skill is the downstream consumer.
• email-capture — Produces DRAFT-NNN capture documents from email threads and documents. This skill is the downstream consumer.
• jira-review — After consolidation produces REQ-XXX requirements, use jira-review to assess readiness for Jira ticket decomposition.
• task-decomposition — Use after jira-review to decompose consolidated requirements into Jira-sized tickets.
• confluence-guide-writer — If the consolidated capture bundle should be published to Confluence, use this skill after PM approval.