Speckit Opsmill Extract

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Goal: Analyze one or more completed spec directories and extract durable knowledge into the project's documentation system (dev/knowledge/, dev/guidelines/, dev/adr/), then mark each spec as extracted.

This command accepts multiple specs as input (space-separated) and processes them sequentially. It operationalizes the documentation lifecycle: specs/ → knowledge/ or guidelines/ (see dev/guidelines/markdown.md).

Phase 0: Setup & Validation

<thinking>
First, resolve all spec directories from the user's arguments and validate each one contains the expected artifacts.
</thinking>

1. Parse arguments — split $ARGUMENTS into individual spec identifiers (space-separated). If $ARGUMENTS is empty, list available spec directories and ask the user to pick one or more.

2. Resolve each spec directory:

   • For each identifier in the arguments:
     • If it matches specs/NNN-* or NNN-*, resolve to REPO_ROOT/specs/NNN-*
     • If it is a bare name like graphql-name-lookup, search specs/ for a matching directory
     • If no match found for an identifier, report it and continue resolving the rest
   • If no identifiers could be resolved, list available spec directories and ask the user to pick

3. Validate each resolved spec:

   • spec.md MUST exist — skip that spec with an error if missing
   • research.md SHOULD exist — warn if missing ("No ADRs can be extracted without research.md") but continue

4. Check extraction status for each spec:

   • If EXTRACTED.md exists in the spec directory, warn the user that this spec was previously extracted
   • Also check if the spec already lives under specs/archive/ — if so, it was previously extracted and archived
   • Ask for confirmation before re-extracting — default is abort
   • The user can choose to skip individual specs from the batch

5. Summarize resolved specs — before proceeding, print the list of specs that will be processed:

   Processing N spec(s):
   1. specs/<spec-name-1>
   2. specs/<spec-name-2>
   ...

6. Load existing documentation index (once, shared across all specs):

   • List all files in dev/knowledge/ (recursively)
   • List all files in dev/guidelines/ (recursively)
   • List all files in dev/adr/ to determine the next ADR number
   • Read the first 20 lines of each knowledge and guidelines file to build a topic index (title + overview section)

7. Load spec artifacts — for each spec, read all available files from its directory:

   • research.md (primary source for ADRs)
   • spec.md (context, scope decisions)
   • data-model.md (schema changes, new methods — if exists)
   • All files in contracts/ (API changes — if exists)
   • plan.md (architectural context — if exists)

Phase 1: Analysis & Classification

<thinking>
For each spec, I need to parse each source and classify content into three buckets: ADR, Knowledge, Guideline. I should also identify content to skip with a clear reason. I'll process specs sequentially and tag each finding with its source spec.
</thinking>

Repeat the following steps for each resolved spec directory. Tag every finding with the source spec name so the extraction plan in Phase 2 groups items by spec.

Step 1: Extract ADR candidates from research.md

Parse each ## R# section in research.md. For each entry:

1. Extract: Decision, Rationale, Alternatives considered, Implementation pattern
2. Determine if it is ADR-worthy using this heuristic:
   • ADR-worthy: Affects system structure, API contracts, data models, error handling strategy, or establishes a pattern used across multiple components
   • Not ADR-worthy: One-off implementation detail with no broader implications (e.g., a local variable naming choice, a single method signature)
3. Draft an ADR title (concise, decision-focused — e.g., "Dual identifier resolution via service-layer helpers")

Also scan spec.md for scope decisions or trade-offs in the Clarifications or Assumptions sections that represent architectural choices worth recording.

Step 2: Extract knowledge candidates

Scan for content that describes how the system works after the feature:

For each finding, map it to a specific existing knowledge file and section. If no existing file fits, propose a new file with a name following kebab-case.md convention.

Step 3: Extract guideline candidates

Scan research.md for implementation patterns that establish repeatable, prescriptive conventions for future code:

• New parameter patterns → dev/guidelines/backend/python.md or dev/guidelines/cyclopts.md
• New error handling conventions → dev/guidelines/backend/exceptions.md
• New API design conventions → dev/guidelines/backend/graphql.md (create if needed)
• New testing patterns → relevant guidelines file

These targets are routing examples, not a fixed map — content moves as files split, so confirm the section still lives in the named file before writing to it.

Only extract patterns that are prescriptive (should be followed in future code). Do NOT extract patterns that are merely descriptive of how this specific feature works — those belong in knowledge.

Step 4: Identify skipped content

For each piece of spec content not classified above, note it with a reason:

• Execution artifacts (plan.md, quickstart.md) — no durable knowledge
• Implementation details already captured in code — no need to duplicate
• One-off decisions with no broader applicability