cognition-alignment

name	cognition-alignment
description	Produces interactive decision reports that bridge the cognition gap between user and agent. Use this skill when you need user direction on architecture, approach, or implementation choices — or when multiple viable paths exist and explicit user input is needed before proceeding. Triggers: 'review decisions', 'align on approach', 'show options', 'what direction', 'help me decide', or whenever the agent recognizes ambiguity that requires user judgment.
argument-hint	[topic or task description requiring alignment]

Cognition Alignment — Interactive Decision Report

You are producing a structured decision report for the user to review interactively in their browser. The goal is to bridge the cognition gap — make sure the user understands the situation, the trade-offs, and can make an informed decision.

When to use this skill

• Before starting a complex implementation (confirm direction)
• When multiple architectural approaches exist
• After analysis when trade-offs need user input
• When you are uncertain about the user's preference
• When the user asks to review options, align on approach, or make a decision

Step 1: Construct the decision report JSON

Build a JSON object. Every field is optional unless marked required.

{
  "version": "1.0",                          // required
  "title": "Short descriptive title",         // required
  "summary": "What was analyzed and why",     // required

  "intro": {                                  // optional — orientation panel
    "whatIsThis": "What this page is and why they're looking at it",
    "flowSteps": ["① Background", "② If we get this wrong", "③ Options", "④ Pick one"],
    "terms": [
      { "term": "Abbreviation", "body": "One-line explanation" }
    ]
  },

  "context": [                                // optional — background sections
    { "heading": "Section title", "body": "What the user should know" }
  ],

  "diagram": "graph LR\n  A --> B --> C",     // optional — overview mermaid diagram

  "decisions": [                              // required — at least 1
    {
      "id": "unique-id",                      // required
      "question": "The decision question?",   // required
      "oneLineSummary": "Quick scan headline (under 60 chars)",
      "severity": "critical|important|consider",
      "background": "What this area is about and why it matters (1-3 sentences)",
      "implication": "What happens if we get this wrong or delay (1-2 sentences)",
      "recommended": "option-id",
      "diagram": "sequenceDiagram\n  ...\n",  // optional — per-decision mermaid diagram
      "options": [                            // required — at least 2
        {
          "id": "option-a",                   // required
          "label": "Short Label",             // required
          "description": "What this entails (1-3 sentences)",
          "pros": ["advantage 1", "advantage 2"],
          "cons": ["disadvantage 1"],
          "effort": "low|medium|high",
          "changes": [                        // optional — before/after diffs
            {
              "file": "path/to/file",
              "before": "current code or config",
              "after": "proposed code or config",
              "why": "why this change"
            }
          ]
        }
      ]
    }
  ],

  "notes": "Any additional context"
}

The user also gets an automatic "Custom answer" option per decision — you don't need to add it.

Writing guidelines

• Include 2-5 decision points. Each with 2-4 options.
• Always write background — explain what this area is about before showing options.
• Always write implication — tell the user what's at stake.
• Use severity: critical (must decide before proceeding), important (should decide soon), consider (low stakes, pick whenever).
• Use intro when the domain has terms the user might not know. flowSteps explains the card layout. terms is a glossary.
• Use diagram at top level for an overview visualization, and/or per-decision for specific flows. Uses Mermaid syntax (graph, flowchart, sequenceDiagram, etc.). Requires internet to render (CDN). Falls back to raw text if offline.
• Use changes[] with before/after diffs when an option involves concrete code or config changes. Highlight key words with <b>...</b> (no other HTML).
• Include 2-4 pros and 2-4 cons per option. Use effort to differentiate.
• Set recommended only when genuinely confident — not as a default.
• Keep labels short (under 10 words). oneLineSummary under 60 chars.
• Write for a non-technical reader. Keep sentences short and direct.

Read the schema at ${SKILL_DIR}/schema/decision-report.schema.json and the example at ${SKILL_DIR}/examples/example-report.json for reference.

Step 2: Generate the interactive HTML

1. Read the template from ${SKILL_DIR}/assets/decision-reviewer.html
2. Replace the placeholder __DECISION_REPORT_JSON__ with your JSON string
3. Write the result to /tmp/decision-review/index.html (create the directory first if needed)
4. Try to open it locally with open /tmp/decision-review/index.html
   • If that fails (e.g. remote SSH or no display), serve it instead: cd /tmp/decision-review && python3 -m http.server 8080 Then tell the user to open http://localhost:8080

Step 3: Tell the user

Say something like:

I've prepared an interactive decision review. It should have opened in your browser. Review each section, pick an option (or write a custom answer), add any notes, then use Copy as Markdown or Copy as JSON to export. Paste the result back here.

Step 4: Process the user's response

When the user pastes back the exported output:

1. Parse the JSON (or Markdown) to extract selections and feedback
2. The export includes full report context — it works in a new session too
3. If selectedOptionId is "__custom__", read the customAnswer field
4. Acknowledge each decision, then proceed with implementation

Exported JSON structure

The exported JSON includes the full report context plus selections:

{
  "report": {
    "title": "...",
    "summary": "...",
    "intro": { ... },
    "context": [ ... ],
    "diagram": "...",
    "notes": "..."
  },
  "exportedAt": "2026-05-07T...",
  "selections": [
    {
      "decisionId": "...",
      "question": "...",
      "oneLineSummary": "...",
      "severity": "...",
      "selectedOptionId": "... or __custom__",
      "selectedLabel": "...",
      "customAnswer": "user's own text, only if __custom__",
      "feedback": "..."
    }
  ],
  "overallFeedback": "..."
}