---
name: blueprint-skeleton
description: >-
  Blueprint Skeleton — Force AI to exhaustively list all decision points from
  8 dimensions (confirmation, ambiguity, assumption, choice, suggestion, exclusion,
  quality, boundary) before starting any task. Generates interactive HTML for
  user to confirm each point, then produces a roadmap. Supports mid-execution
  re-alignment when new divergences emerge. Solves "user is vague, AI guesses,
  result is off-target" problem. Zero dependencies, pure Python 3.8+.
  Triggers: blueprint, skeleton, align, confirm requirements, before starting.
---

# Blueprint Skeleton

## What It Solves

The biggest efficiency loss between user and AI comes from **understanding drift**:
- User describes goals vaguely
- AI doesn't ask, guesses on its own, starts working
- Result is off-target, rework wastes hours

Blueprint Skeleton turns "think before you act" into a **forced workflow**:
before starting, AI must exhaustively list all decision points from 8 dimensions,
generate an interactive HTML page for the user to confirm each point,
then produce a roadmap and follow it.

## When to Trigger

**Must trigger:**
- User explicitly says "align", "blueprint", "skeleton", "confirm first"
- Multi-step task with clear deliverables or decision points
- User's description is vague, multiple interpretations possible
- Cross-file or cross-module changes, high-risk or irreversible operations

**Skip:**
- Pure conversation, simple queries, direct Q&A
- Single-file minor edits
- User has already described everything in detail

## 8-Dimension Alignment Framework

### 1. Confirmation (type: confirmation)
Confirm AI's understanding matches user intent. What's the goal? Deliverable? Format? Scope? Hidden expectations?

### 2. Ambiguity (type: ambiguity)
Eliminate fuzzy areas. Terms with multiple meanings? "Approximate" = what exactly? Naming conventions?

### 3. Assumption (type: assumption)
Surface assumptions AI is silently making. Tech stack choices? Dependencies? Environment constraints?

### 4. Choice (type: choice)
When multiple implementation paths exist, let user choose. Pros/cons of each? Which fits user's style and project?

### 5. Suggestion (type: suggestion)
AI proactively suggests improvements, but user decides whether to adopt. Better approach? Bonus optimization? Industry best practices?

### 6. Exclusion (type: exclusion)
Explicitly define what's NOT in scope. What's excluded? Things that could be done but shouldn't be?

### 7. Quality (type: quality)
Define "done" and "good". What criteria? Testing required? Code quality standards?

### 8. Boundary (type: boundary)
Define external boundaries and constraints. Delivery format? Time limits? Files/dirs that must not be touched?

## Forced Workflow

### Step 1: Analyze task from 8 dimensions

Go through each dimension. Found points needing alignment → generate alignment points (2-4 options each). None → skip.

### Step 2: Generate alignment JSON

```json
{
  "task": {
    "title": "Short task title",
    "summary": "1-2 sentence description",
    "timestamp": "ISO 8601"
  },
  "sections": [
    {
      "title": "Dimension name",
      "type": "confirmation|ambiguity|assumption|choice|suggestion|exclusion|quality|boundary",
      "icon_text": "1-2 char icon",
      "points": [
        {
          "id": "unique_id",
          "type": "same as section type",
          "label": "Short label",
          "description": "Why this needs alignment",
          "options": [
            {"label": "Option summary", "value": "machine_readable_value", "detail": "Explanation"}
          ]
        }
      ]
    }
  ]
}
```

### Step 3: Generate interactive HTML

```bash
python "{SKILL_DIR}/scripts/generate_interactive.py" --input alignment.json --output blueprint_review.html --auto-clean
```

`{SKILL_DIR}` = the directory containing this SKILL.md file.

`--auto-clean` automatically deletes previous alignment HTML files in the output directory.

### Step 4: Present and wait

```
I've generated an interactive confirmation page. Please open it in your browser:

[file path]

There are N alignment points covering:
- Confirmation: x points
- Ambiguity: x points
- ...

Please select each point on the page, then click "Confirm & Generate Roadmap".
Export the JSON and paste it back to me.
```

**AI MUST stop here and wait for user response. Must NOT start the task or guess user's choices.**

### Step 5: Parse result into roadmap

```bash
python "{SKILL_DIR}/scripts/parse_response.py" --input alignment_result.json --output roadmap.md
```

### Step 6: Present roadmap for final confirmation

```
Based on your confirmations, here's the execution roadmap:

1. [Confirmation] Scope -> Only refactor rendering code
2. [Ambiguity] Naming -> renderer.py
...

Excluded:
- ~~AI decision logic refactor~~ — user marked as N/A

Shall I proceed? Anything to adjust?
```

**AI MUST stop and wait for user's final confirmation.**

### Step 7: Execute the roadmap

After user confirms, start working. During execution:
- Follow the roadmap strictly, don't deviate on your own
- **When encountering new divergence → trigger mid-execution re-alignment** (see below)

## Mid-Execution Re-Alignment

### When to trigger

AI must pause and trigger re-alignment when any of these occur:

1. **Decision point not covered in roadmap**: A step requires a choice the roadmap didn't cover
2. **Technical path blocked**: Original plan hits an unsolvable technical obstacle
3. **Scope adjustment needed**: Task scope needs to expand or shrink
4. **Intermediate result changes path**: A step's outcome changes the planned approach
5. **User feedback says direction is wrong**: User sees intermediate output and wants adjustment

### Re-alignment flow

1. **Pause execution** — don't continue
2. **Analyze new divergence** — find newly emerged alignment points
3. **Generate supplementary JSON** — only new points, not full 8 dimensions
4. **Generate HTML and present** — same generate_interactive.py script
5. **Wait for user confirmation**
6. **Update roadmap** — append new decisions to existing roadmap
7. **Continue execution**

### Scale-based handling

- **Small divergence** (1-2 points): No HTML needed, list options in text, user picks, continue
- **Medium divergence** (3-5 points): Generate HTML page, wait for confirmation
- **Large divergence** (6+ points or core direction change): Re-run full 8-dimension alignment

### Limits

- Max 3 re-alignments per execution
- If triggering frequently (>3 times), initial alignment was insufficient — stop and re-discuss overall plan with user
- Re-alignment appends to existing roadmap, doesn't start over

## Key Rules

1. **Never start before alignment is complete.**
2. **Never guess when user is vague.**
3. **Never skip dimension thinking.** Even if no points, must actively consider each.
4. **Never auto-adopt suggestions.** AI suggests, user decides.
5. **Never expand scope without confirmation.**
6. **Must surface assumptions.**
7. **Give options, not conclusions.**
8. **Must trigger re-alignment on new divergences during execution.**
9. **Simple tasks can skip.** If analysis shows no divergence points, just start.

## CLI Reference

```bash
# Generate interactive HTML (--auto-clean deletes previous HTML files)
python "{SKILL_DIR}/scripts/generate_interactive.py" --input alignment.json --output blueprint_review.html --auto-clean

# Parse confirmation result
python "{SKILL_DIR}/scripts/parse_response.py" --input result.json --output roadmap.md

# Demo mode
python "{SKILL_DIR}/scripts/generate_interactive.py" --output demo.html --demo
```

## Files

- `scripts/generate_interactive.py` — Generate interactive HTML page (1087 lines)
- `scripts/parse_response.py` — Parse user confirmation results into roadmap (121 lines)
- `SKILL.md` — This file

## Limitations

- HTML page requires user to manually open in browser
- User must manually export JSON and paste back to AI
- Alignment quality depends on AI's analysis depth
- May be overkill for very simple tasks (skip in that case)