VALIDATING Phase

VALIDATING Phase

The VALIDATING phase runs the completeness gate to ensure the design is ready for implementation.

Purpose

• Verify all required sections are present
• Check for completeness and clarity
• Ensure no TBDs or ambiguous items remain
• Gate the transition to rough-draft

Required Sections

The design doc must contain all of these:

• Problem/​Goal - Clear statement of what we're solving and why
• Key Decisions - At least one documented decision with rationale
• At least one diagram - Visual representation of architecture, flow, or UI
• Success Criteria - Measurable, testable criteria (not "works well")
• Out of Scope - Explicit boundaries on what this work does NOT include

Gate Check Process

# Read design doc
cat .collab/<name>/​documents/​design.md

# Verify each required section exists and has content
# If any section is missing or empty, do NOT proceed

For each section, verify:

1. Section header exists
2. Section has substantive content (not just placeholder text)
3. Content is specific, not vague

Single-Item Mode (VALIDATING)

When currentItem is set in collab-state.json:

Check item has all required fields filled:

• Problem/​Goal filled
• Approach filled
• Success Criteria filled

If validation fails: Return to DESIGNING to fill gaps

If validation passes:

1. Mark item as documented in workItems:

   Tool: mcp__plugin_mermaid-collab_mermaid__get_session_state
   Args: { "project": "<cwd>", "session": "<session>" }
   

   Update the item's status in workItems array:

   Tool: mcp__plugin_mermaid-collab_mermaid__update_session_state
   Args: {
     "project": "<cwd>",
     "session": "<session>",
     "workItems": [<updated array with item status changed to "documented">]
   }
   

2. Update design doc status:

   Tool: mcp__plugin_mermaid-collab_mermaid__patch_document
   Args: {
     "project": "<cwd>",
     "session": "<session>",
     "id": "design",
     "old_string": "### Item N: <title>\n**Type:** <type>\n**Status:** pending",
     "new_string": "### Item N: <title>\n**Type:** <type>\n**Status:** documented"
   }
   

3. Display: "Item documented. Returning to work item loop."

Important: In single-item mode, do NOT:

• Run the full completeness gate
• Transition to rough-draft

If Gate Fails

1. Identify which sections are incomplete
2. List the specific gaps found
3. Return to DESIGNING phase to fill gaps
4. Do NOT proceed to rough-draft until all sections pass

Example failure message:

Completeness gate failed:

Missing or incomplete:
- [ ] Key Decisions - No decisions documented
- [ ] Out of Scope - Section is empty

Returning to DESIGNING phase to address these gaps.

If Gate Passes

Show summary and ask for confirmation:

Brainstorming complete. Design covers:
- [Bullet 1: key topic from design]
- [Bullet 2: key topic from design]
- [Bullet 3: key topic from design]

Ready to move to rough-draft?

1. Yes
2. No

Response handling:

• 1 (Yes): Transition to rough-draft (invoke brainstorming-transition skill)
• 2 (No): Ask what else needs to be explored, return to appropriate phase

Browser-Based Confirmation

When collab session is active, use render_ui for the confirmation:

Tool: mcp__plugin_mermaid-collab_mermaid__render_ui
Args: {
  "project": "<absolute-path-to-cwd>",
  "session": "<session-name>",
  "ui": {
    "type": "Card",
    "props": { "title": "Confirm" },
    "children": [{
      "type": "Markdown",
      "props": { "content": "Do you want to proceed?" }
    }],
    "actions": [
      { "id": "yes", "label": "Yes", "primary": true },
      { "id": "no", "label": "No" }
    ]
  },
  "blocking": true
}

Response: { "action": "yes" } or { "action": "no" }

Exit Criteria

• All required sections present and complete
• No TBDs or "figure out later" items
• User confirmed ready to proceed

Transition to Rough-Draft

Prerequisites:

• Completeness checklist passed
• User confirmed ready

Announce: "Completeness gate passed. Transitioning to rough-draft skill."

Invoke skill: brainstorming-transition

Completion

At the end of this skill's work, call complete_skill:

Tool: mcp__plugin_mermaid-collab_mermaid__complete_skill
Args: { "project": "<cwd>", "session": "<session>", "skill": "brainstorming-validating" }

Handle response:

• If action == "clear": Invoke skill: collab-clear
• If next_skill is not null: Invoke that skill
• If next_skill is null: Workflow complete