Collab Session Required

Before proceeding, check for active collab session:

Check if .collab/ directory exists
Check if any session folders exist within

If no session found:

No active collab session found.

Use /collab to start a session first.

STOP - do not proceed with this skill.

If multiple sessions exist, check COLLAB_SESSION_PATH env var or ask user which session.

Rough-Draft: From Design to Implementation

RESTRICTIONS

FORBIDDEN during rough-draft phase:

Edit tool on source files (only allowed in .collab/ folder)
Write tool on source files (only allowed in .collab/ folder)
Any file modification outside .collab/ folder
Implementing code directly (must go through executing-plans)

ALLOWED during rough-draft:

MCP collab tools - prefer patch operations for efficiency:
- patch_document for targeted edits (status changes, adding fields)
- patch_diagram for small diagram updates
- update_document/update_diagram only for large rewrites or new sections
- create_diagram, create_document for new artifacts
Read tool (for exploration and context)
Bash tool (for non-destructive commands like ls, git status)

Why this matters:

Editing source files during rough-draft bypasses executing-plans
This skips TDD, spec compliance, and code review gates
All implementation MUST go through executing-plans with subagent dispatch

RED FLAG: If you're about to use Edit or Write on a source file, STOP. You're in the wrong phase. Document changes in the design doc and wait for executing-plans.

Overview

The rough-draft skill bridges the gap between brainstorming (design) and implementation. It progressively refines the design through 4 phases, with verification gates at each transition to catch drift early.

+--------------+     +--------------+     +--------------+     +--------------+
|  Interface   |---->|  Pseudocode  |---->|   Skeleton   |---->|  Implement   |
+------+-------+     +------+-------+     +------+-------+     +------+-------+
       |                    |                    |                    |
       v                    v                    v                    v
  +--------+           +--------+           +--------+           +--------+
  | Verify |           | Verify |           | Verify |           | Verify |
  +--------+           +--------+           +--------+           +--------+

Announce at start: "I'm using the rough-draft skill to refine the design through interface, pseudocode, skeleton, and implementation handoff."

Auto-Accept Prompt (At Start)

When first invoking rough-draft, ask user for approval workflow preference:

Render UI Dropdown:

Tool: mcp__plugin_mermaid-collab_mermaid__render_ui
Args: {
  "project": "<absolute-path-to-cwd>",
  "session": "<session-name>",
  "ui": {
    "type": "Card",
    "props": { "title": "Rough-Draft Workflow Preference" },
    "children": [{
      "type": "Markdown",
      "props": { "content": "How should I handle [PROPOSED] artifact reviews during rough-draft phases?" }
    }],
    "children": [{
      "type": "RadioGroup",
      "props": {
        "name": "autoAccept",
        "options": [
          { "value": "yes", "label": "Yes - Skip approval prompts" },
          { "value": "no", "label": "No - Review each phase" }
        ]
      }
    }]
  },
  "blocking": true
}

Store preference in session state:

Tool: mcp__plugin_mermaid-collab_mermaid__update_session_state
Args: {
  "project": "<absolute-path-to-cwd>",
  "session": "<session-name>",
  "metadata": { "autoAcceptRoughDraft": true/false }
}

Use preference in phases:

If autoAcceptRoughDraft: true - Automatically proceed with [PROPOSED] artifacts without approval prompts
If autoAcceptRoughDraft: false - Always ask for approval before removing [PROPOSED] markers

This preference applies to all Interface, Pseudocode, and Skeleton phase artifacts.

Prerequisites

Before starting rough-draft, ensure:

Design doc exists at .collab/<name>/documents/design.md
Design doc passed brainstorming's completeness gate
collab-state.json phase is set to rough-draft/interface

Writing Quality

When writing interfaces and pseudocode, use clear, precise language.

If obra/the-elements-of-style plugin is available, invoke it for guidance on:

Omitting needless words
Using active voice
Being specific, not vague

Apply these principles to interface documentation and pseudocode comments.

Phase 1: Interface

Define the structural contracts of the system - file paths, class/function signatures, public API contracts, and type definitions.

Invoke skill: rough-draft-interface for detailed instructions.

Compaction Checkpoint: Interface → Pseudocode

After Interface phase completes and is approved:

Check your current context usage and ask user: "Context is [X]% full. Ready to compact before Pseudocode phase?"

1. Yes - compact now
2. No - continue without compaction

If 1 (Yes): Invoke skill: collab-compact, then continue to Pseudocode
If 2 (No): Continue to Pseudocode without compaction

Phase 2: Pseudocode

Define the logic flow for each function - step-by-step descriptions, error handling, edge cases, and dependencies.

Invoke skill: rough-draft-pseudocode for detailed instructions.

Compaction Checkpoint: Pseudocode → Skeleton

After Pseudocode phase completes and is approved:

Check your current context usage and ask user: "Context is [X]% full. Ready to compact before Skeleton phase?"

1. Yes - compact now
2. No - continue without compaction

If 1 (Yes): Invoke skill: collab-compact, then continue to Skeleton
If 2 (No): Continue to Skeleton without compaction

Phase 3: Skeleton

Generate stub file documentation and task dependency graphs. Files are documented but NOT created - they are created during implementation by executing-plans.

Invoke skill: rough-draft-skeleton for detailed instructions.

Compaction Checkpoint: Skeleton → Implementation

After Skeleton phase completes and is approved:

Check your current context usage and ask user: "Context is [X]% full. Ready to compact before Implementation?"

1. Yes - compact now
2. No - continue without compaction

If 1 (Yes): Invoke skill: collab-compact, then continue to Implementation Handoff
If 2 (No): Continue to Implementation Handoff without compaction

Proposed Tag Workflow

For each phase (INTERFACE, PSEUDOCODE, SKELETON), use the proposed tag workflow before verification:

Write artifact to design doc with [PROPOSED] marker
Tell user: "I've added the [interface/pseudocode/skeleton] to the design doc. Please review."
Ask: "Does this look right?"
```
1. Yes
2. No
```
If 1 (Yes): remove [PROPOSED] marker, proceed to drift check
If 2 (No): discuss, revise, repeat

This ensures user reviews each artifact before it becomes part of the design.

Drift Detection

After each phase's [PROPOSED] content is accepted, check if it matches the original design.

When to Check for Drift

Run drift detection after each phase's artifact is accepted:

After INTERFACE accepted - compare to original design
After PSEUDOCODE accepted - compare to design + interface
After SKELETON accepted - compare to design + interface + pseudocode

Presenting Drift

When drift is detected, present it clearly:

**Drift detected:** [What changed]

**Original design:** [What the design doc specified]
**Current artifact:** [What was just produced]

**Pros:**
- [Benefit 1]
- [Benefit 2]

**Cons:**
- [Drawback 1]
- [Drawback 2]

**Recommendation:** [Keep/Discard] - [Reasoning]

Keep this change?

1. Yes
2. No

If User Keeps Change (1)

Design doc is already updated (via accepted proposal)
Assess significance:
- Minor: Affects one component, no architectural change
- Significant: Affects multiple components or changes architecture
Present: "This is [minor/significant] because [reasons]. I recommend [continuing/returning to brainstorming]."
Ask: "Go back to brainstorming?"
```
1. Yes
2. No
```
If 1 (Yes) - transition to brainstorming skill
If 2 (No) - continue to next rough-draft phase

If User Discards Change (2)

Revert the design doc to before the proposal
Recommend restart point:
- Beginning (INTERFACE): If drift affects foundational decisions
- Current phase: If drift is isolated to this phase
Present: "I recommend restarting from [beginning/current phase] because [reasons]."

Ask: "Restart from?"

1. Beginning (INTERFACE)
2. Current phase

Execute the restart

Phase 4: Implementation Handoff

Hand off to executing-plans with the dependency graph. Includes options for current directory or git worktree isolation.

Invoke skill: rough-draft-handoff for detailed instructions.

Verification Gate Details

When to Verify

Run verification BEFORE each phase transition:

Interface -> Pseudocode
Pseudocode -> Skeleton
Skeleton -> Implementation
Implementation -> Complete

How Verification Works

The verify-phase.sh hook:

Reads the design document
Compares current artifacts to the design
Identifies alignment and drift
Generates pros/cons for each drift
Presents a report to the user

Handling Verification Results

If drift detected:

The hook outputs a report with aligned items, drift detected items with pros/cons, and options to accept all, reject all, or review each.

User Decisions

1 - Accept all:

Design doc is updated to include the drift
Decision logged with rationale
Proceed to next phase

2 - Reject all:

Design doc unchanged
All drifts added to pendingVerificationIssues
Stay in current phase, fix code

3 - Review each:

Go through each drift one by one
Accept/reject individually
Mixed results: some accepted (update design), some rejected (add to pending)

Decision Log

Accepted drifts are logged in the design doc:

## Decision Log

### 2025-01-18: Added refreshToken method
- **Phase:** rough-draft:interface
- **Original:** Not specified
- **Changed to:** Added `refreshToken(token: string): Promise<string>`
- **Reason:** Enables session extension, security best practice

State Tracking

collab-state.json Updates

Track the current phase:

{
  "phase": "rough-draft/interface",
  "template": "feature",
  "lastActivity": "2025-01-18T10:30:00Z",
  "pendingVerificationIssues": [],
  "serverPid": 12345,
  "serverPort": 3737
}

Phase values for rough-draft:

rough-draft/interface
rough-draft/pseudocode
rough-draft/skeleton
implementation

Pending Verification Issues

When drifts are rejected:

{
  "pendingVerificationIssues": [
    {
      "type": "drift",
      "phase": "interface",
      "description": "Added refreshToken method not in design",
      "file": "src/auth/service.ts",
      "detectedAt": "2025-01-18T11:00:00Z"
    }
  ]
}

Issues must be resolved before phase transition.

Snapshot Saving

Save context snapshots to enable recovery after compaction.

When to Save

Call saveSnapshot() after:

User accepts proposed interface/pseudocode/skeleton
Before transitioning to next phase
Before invoking executing-plans

Save Function

FUNCTION saveSnapshot():
  session = current session name

  # Read current state via MCP
  Tool: mcp__plugin_mermaid-collab_mermaid__get_session_state
  Args: { "project": "<cwd>", "session": session }
  Returns: state = { "phase": "...", ... }

  # Save snapshot via MCP
  Tool: mcp__plugin_mermaid-collab_mermaid__save_snapshot
  Args: {
    "project": "<cwd>",
    "session": session,
    "activeSkill": "rough-draft",
    "currentStep": state.phase (e.g., "rough-draft/interface"),
    "inProgressItem": null,
    "pendingQuestion": null,
    "recentContext": []
  }
  # Note: version and timestamp are automatically added

  # Update state to mark snapshot exists
  Tool: mcp__plugin_mermaid-collab_mermaid__update_session_state
  Args: { "project": "<cwd>", "session": session, "hasSnapshot": true }

Save Points

After user accepts proposal:

[User accepts interface/pseudocode/skeleton]
-> Remove [PROPOSED] marker
-> saveSnapshot()
-> Run drift check
-> Continue to next phase

At phase transitions:

[Phase complete (interface -> pseudocode -> skeleton)]
-> Update collab-state.json phase via MCP
-> saveSnapshot()
-> Continue to next phase

Before invoking executing-plans:

[Skeleton complete, user confirms implementation]
-> saveSnapshot()
-> Invoke executing-plans skill

Task Dependency Graph Format

YAML Structure

tasks:
  - id: <unique-identifier>
    files: [<file-path>, ...]
    description: <what this task implements>
    parallel: true  # Optional: can run with other parallel tasks
    depends-on: [<task-id>, ...]  # Optional: must complete first

Rules

IDs are unique - No duplicate task IDs
Files are explicit - Full paths from project root
Dependencies are task IDs - Not file paths
Parallel means independent - No shared state, no order requirement
No circular dependencies - Graph must be acyclic

Context Full Detection

During any rough-draft phase, if context usage approaches capacity, render a non-blocking Alert to notify the user:

Tool call:

Tool: mcp__plugin_mermaid-collab_mermaid__render_ui
Args: {
  "project": "<absolute-path-to-cwd>",
  "session": "<session-name>",
  "ui": {
    "type": "Alert",
    "props": {
      "type": "warning",
      "title": "Context Full",
      "message": "Run /compact in terminal, then /collab to resume."
    }
  },
  "blocking": false
}

This provides early warning before compaction becomes critical.

Browser-Based Questions

When a collab session is active, prefer render_ui for user interactions instead of terminal prompts. Use mcp__plugin_mermaid-collab_mermaid__render_ui with Card components containing MultipleChoice or action buttons.

Integration

Called By

brainstorming skill - After completeness gate passes
collab skill - When resuming at rough-draft phase

Transitions To

executing-plans skill - With task dependency graph for implementation

Collab Workflow Context

When invoked from collab workflow:

.collab/<name>/ folder exists
collab-state.json tracks phase
Mermaid-collab server running on assigned port
Design doc at .collab/<name>/documents/design.md

Context Preservation

If context is lost (compaction), re-read state:

# Get current session state
Tool: mcp__plugin_mermaid-collab_mermaid__get_session_state
Args: { "project": "<cwd>", "session": "<name>" }

# Read design doc
Tool: Read
Args: { "file_path": ".collab/<name>/documents/design.md" }

# Determine where to resume based on phase from state

Quick Reference

| Phase | Input | Output | Verification Focus | |-------|-------|--------|-------------------| | Interface | Design doc | File paths, signatures, types | Completeness, no any types | | Pseudocode | Interface section | Logic flow, error handling | Every function covered | | Skeleton | Pseudocode section | Stub files, dependency graph | Files created, TODOs match | | Implementation | Dependency graph | Completed code | Tests pass, design match |

Common Mistakes

Skipping verification gates

Problem: Drift accumulates, implementation diverges from design
Fix: Always run verify-phase.sh before phase transitions

Vague pseudocode

Problem: Implementation guesses at details, introduces drift
Fix: Pseudocode should be detailed enough to implement mechanically

Missing dependencies in graph

Problem: Tasks fail because prerequisites not met
Fix: Trace all imports and analyze what must exist first

Not updating collab-state.json

Problem: Resume doesn't know current phase
Fix: Use mcp__plugin_mermaid-collab_mermaid__update_session_state after each transition (automatically updates lastActivity)

Red Flags

Never:

Skip a phase (each builds on the previous)
Proceed with pending verification issues
Modify design doc without going through verification
Create files not in the Interface phase
Add functionality not in the Pseudocode phase

Always:

Run verification before phase transition
Handle drift explicitly (accept/reject)
Update collab-state.json with current phase
Keep design doc synchronized with decisions
Use mermaid-collab for visualizing dependency graphs