Workflow Specification Process

Specification Process

Act as expert technical architect and specification builder. Collaborate with the user to transform source material into validated, standalone specifications.

Your role is to synthesize reference material, present it for validation, and build a specification that formal planning can execute against.

Purpose in the Workflow

Follows discussion (or investigation for bugfix). Transform prior-phase source material — discussions, research notes, investigation findings — into a specification that's standalone and approved.

What This Skill Needs

• Source material (required) - Prior-phase artifacts to synthesize (discussions, research, investigation findings)
• Topic name (required) - Used for the output filename

If source material seems incomplete or unclear:

Output the next fenced block as markdown (not a code block):

I have the source material, but {concern}. Should I proceed as-is, or is there additional material I should review?

STOP. Wait for user response.

Multiple sources: When multiple prior-phase artifacts are provided, extract exhaustively from ALL of them. Content may be scattered across sources — a decision in one discussion may have constraints or details in another. The specification consolidates everything into a single standalone document.

Instructions

Load framework.md and follow its instructions as written.

Resuming After Context Refresh

Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:

1. Re-read this skill file completely, then re-load framework.md. Do not rely on your summary of either, and re-read both even if you believe they are already loaded — that belief is what a summary feels like from the inside. The full process, steps, and rules must be reloaded.
2. Read all tracking and state files for the current topic — the specification file, review tracking files, or any working documents this skill creates. These are your source of truth for progress.
3. Check git state. Run git status and git log --oneline -10 to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
4. Announce your position to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
5. Check finding_gate_mode and construction_gate_mode via engine manifest (node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.specification.{topic} finding_gate_mode and ... construction_gate_mode) — if either is auto, the user previously opted in during this session. Preserve that value.

Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.

Hard Rules

1. STOP AND WAIT for explicit approval before any write to the specification. Present content, wait for the user to explicitly approve (y/yes or equivalent), then log. No exceptions.
2. Log verbatim — when approved, write exactly what was presented. No silent modifications.
3. Commit frequently — commit at natural breaks and before any context refresh. Context refresh = lost work. Commits go through the scoped helper, action-scoped to this topic — the specification directory and the work-unit manifest, never a sibling session's files:

   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "{message}" --topic specification/{topic}
   

Step 0: Resume Detection

Refresh the tmux session label — a no-op unless the user opted in and this session runs inside tmux:

node .claude/skills/workflow-engine/scripts/engine.cjs session label {work_unit} specification {topic}

Check if .workflows/{work_unit}/specification/{topic}/specification.md exists.

If no file exists

→ Proceed to Step 1.

If file exists

Output the next fenced block as markdown (not a code block):

**`□ Resume Detection`**

Output the next fenced block as markdown (not a code block):

> An in-progress specification exists for this topic — choose whether to pick it up or start fresh.

Load resume-detection.md with artifact = specification, file = .workflows/{work_unit}/specification/{topic}/specification.md, continue_step = Step 3, restart_targets = the specification file and all review tracking files (review-*-tracking-c*.md) in .workflows/{work_unit}/specification/{topic}/, restart_resets = every sources.{name}.status and consult_references.{name}.status row under {work_unit}.specification.{topic} to pending via engine manifest set — initialization never overwrites an existing row, so without this reset the fresh file would never get its content re-extracted — and the tracking subtree and review_baseline_words deleted where present (engine manifest delete {work_unit}.specification.{topic} tracking, then the same for review_baseline_words — an absent field's delete errors and is skipped) to match the deleted tracking files, commit = spec({work_unit}): restart specification.

Step 1: Verify Source Material

Load verify-source-material.md and follow its instructions as written.

→ On return, proceed to Step 2.

Step 2: Initialize Specification

Load initialize-specification.md and follow its instructions as written.

→ On return, proceed to Step 3.

Step 3: Session Setup

Load session-setup.md and follow its instructions as written.

→ On return, proceed to Step 4.

Step 4: Load Specification Principles

Load specification-principles.md and follow its instructions as written.

→ On return, proceed to Step 5.

Step 5: Spec Construction

Output the next fenced block as markdown (not a code block):

**`□ Spec Construction`**

Output the next fenced block as markdown (not a code block):

> Building the specification. Topics from your source material will be extracted and presented one at a time. Nothing gets written without your explicit approval.

Load spec-construction.md and follow its instructions as written.

→ On return, proceed to Step 6.

Step 6: Document Dependencies

If work_type is not epic

→ Proceed to Step 7.

Otherwise

Output the next fenced block as markdown (not a code block):

**`□ Document Dependencies`**

Output the next fenced block as markdown (not a code block):

> Recording cross-topic dependencies — for epics, specifications may depend on each other.

Load dependencies.md and follow its instructions as written.

→ On return, proceed to Step 7.

Step 7: Specification Review

Output the next fenced block as markdown (not a code block):

**`□ Specification Review`**

Output the next fenced block as markdown (not a code block):

> Reviewing the specification. Agents will measure its claims against the codebase and analyse it against source material for gaps and inconsistencies. Settled findings carry their fix; genuine choices stop for your call, and any finding can be talked through — adjusted, challenged, or declined.

Load spec-review.md and follow its instructions as written.

→ On return, proceed to Step 8.

Step 8: Compliance Self-Check

Load compliance-check.md and follow its instructions as written.

→ On return, proceed to Step 9.

Step 9: Assess Cross-Cutting & Conclude

Output the next fenced block as markdown (not a code block):

**`□ Conclude`**

Output the next fenced block as markdown (not a code block):

> Wrapping up. Final assessment, sign-off, and @if(work_type is cross-cutting) closure — the pipeline completes here @else handover to the planning phase @endif.

Load spec-completion.md and follow its instructions as written.