rustyrazorblade/openspec-consolidate-specs

Review OpenSpec specs for overlapping functionality and propose consolidation.

When to trigger:

• After archiving a change that added or modified specs
• When the user explicitly asks to review specs for overlap
• When you notice during exploration that multiple specs cover the same system

Steps

1. Read all specs

   List directories under openspec/specs/ and read each spec.md. Use parallel subagents to read specs in batches grouped by domain (observability, cluster infrastructure, databases, etc.).

   For each spec, note: scope, key requirements, technologies/components, file paths and port numbers mentioned.

2. Identify overlap candidates

   Look for specs that:

   • Describe the same system from different angles (e.g., installation vs. runtime behavior vs. configuration)
   • Cover producer and consumer of the same data flow (e.g., one spec generates logs, another collects them)
   • Are a strict subset of a broader spec (e.g., detailed spec for one section of a parent spec)
   • Share the same file paths, ports, or component names

3. Propose merges (max 3 candidates)

   For each candidate, present:

   • Which specs to merge and why they overlap
   • A proposed new name (use a broader, more descriptive term)
   • What the merged structure would look like (requirement sections)
   • Whether any content would be lost or needs careful reconciliation
   • Any conflicts between the specs (inconsistent paths, ports, or behaviors)

   Let the user pick which (if any) to proceed with.

4. Execute merge (when approved)

   • Create the new spec directory under openspec/specs/<new-name>/
   • Write the merged spec.md preserving all scenarios from both sources
   • Unify terminology and remove duplication (e.g., if both specs describe the same installation step, keep one)
   • If the old specs used different approaches (e.g., file-based logs vs journald), use the newer/correct approach
   • Remove old spec directories
   • Check for references to old spec names in openspec/changes/ and note them (archived changes don't need updating, but active changes do)

Naming guidelines:

• Prefer names that describe the capability not the component (e.g., tool-execution not exec-logging)
• Prefer names that cover the full scope of the merged spec (e.g., emr-node-observability not spark-node-otel-collector)
• Use kebab-case

Guardrails:

• Never merge specs that cover genuinely different systems just because they share a technology
• Always check for conflicts before merging — inconsistent details need resolution, not silent dropping
• Present candidates to the user before executing any merge
• Preserve all scenarios from source specs — merging reduces files, not coverage