Design /think-with-me-about using the Insight Surface Loop

[ramsani]

Intent

Design and implement a KISS, lean, and fast thinking workflow for html-explainer:

/think-with-me-about <topic>

The command should help users think through a topic iteratively with decision-ready HTML, moving from vague or scattered thinking toward clearer insight, stronger conclusions, better next actions, and reusable local knowledge.

The user-facing command should be simple and natural.

The underlying method should be rigorous:

Insight Surface Loop

Core promise

A user should be able to enter with an unclear idea, question, decision, strategy, concern, or opportunity and quickly get a visual thinking surface that helps them:

• frame what they are really thinking about;
• expand perspectives without getting lost;
• ground the discussion in evidence and known constraints;
• expose assumptions, tensions, risks, and contradictions;
• stress-test the idea through inversion;
• synthesize a provisional conclusion;
• decide the next action;
• preserve useful insight into local artifact memory when valuable;
• continue the next thinking cycle with a copy-ready prompt.

Product principle

This must feel simple to the user.

The system may use strong thinking models internally, but the user should not feel like they are filling a heavy consulting worksheet.

The ideal experience is:

User: /think-with-me-about <topic>
System: creates a clear HTML thinking surface that quietly guides the user toward better insight.

Why this belongs in html-explainer

This repo is already built around:

intent -> evidence -> visual understanding -> decision -> expert next prompt

/think-with-me-about extends that core path from explaining decisions to actively helping users form better conclusions.

The HTML artifact is justified when thinking requires multiple visible layers at once:

• context;
• evidence;
• assumptions;
• tensions;
• risks;
• perspectives;
• models;
• options;
• provisional conclusion;
• next prompt;
• knowledge preservation.

Markdown can explain these pieces sequentially. HTML can keep them visible, comparable, filterable, and reusable.

Underlying method: Insight Surface Loop

The method should use this loop:

Frame -> Expand -> Ground -> Stress -> Synthesize -> Decide -> Preserve -> Re-enter

1. Frame

Clarify what the user is really trying to think about.

Required outputs:

• topic;
• real question;
• decision or insight sought;
• context;
• constraints;
• why this matters now.

2. Expand

Open the thinking space before narrowing too early.

Possible lenses:

• perspectives;
• stakeholders;
• alternatives;
• hidden options;
• adjacent problems;
• opportunity angles;
• second-order consequences.

3. Ground

Separate what is known from what is assumed.

Required categories:

• facts;
• evidence;
• inferences;
• assumptions;
• hypotheses;
• unknowns;
• constraints.

4. Stress

Attack the idea before trusting it.

Required moves:

• inversion: how could this fail?
• pre-mortem: what would make this look foolish later?
• contradiction check;
• weakest assumption;
• missing evidence;
• downside and opportunity cost.

5. Synthesize

Reduce noise into insight.

Required outputs:

• emerging pattern;
• strongest insight;
• provisional conclusion;
• confidence level;
• what would change the conclusion.

6. Decide

Convert thinking into action.

Required outputs:

• recommended next action;
• smallest useful experiment;
• what to stop doing;
• what to investigate next;
• decision status: decide now / investigate / defer / reject / reframe.

7. Preserve

Decide whether the artifact should enter local artifact memory.

Required outputs:

• archive recommendation: save / do not save;
• suggested validity: temporal / replaceable / evergreen / private / do-not-reuse;
• freshness risk;
• suggested title;
• suggested tags;
• why preserve or discard.

8. Re-enter

Prepare the next cycle.

Required outputs:

• next thinking prompt;
• focused follow-up question;
• evidence needed before next cycle;
• block conditions.

Internal thinking models to use quietly

The user should not have to choose a thinking model manually.

The system should pick useful lenses based on the topic.

Candidate models:

• Socratic questioning;
• inversion;
• pre-mortem;
• first principles;
• second-order thinking;
• Feynman technique;
• ladder of inference;
• Cynefin-style problem typing;
• OODA-style iteration;
• Double Diamond divergence/convergence;
• trade-off analysis;
• decision matrix;
• opportunity cost;
• systems thinking;
• constraint analysis.

Do not overload the artifact with theory names. Show the thinking effect, not an academic lecture.

User-facing command

Add a new command:

/think-with-me-about

Command behavior:

/think-with-me-about <topic, idea, question, decision, strategy, problem, or opportunity>

The command should:

1. Apply docs/DECISION_GATE.md.
2. Use HTML only if the topic benefits from a visual thinking surface.
3. Apply the Insight Surface Loop.
4. Build a fact sheet.
5. Separate facts, inferences, assumptions, hypotheses, and unknowns.
6. Generate the smallest useful HTML artifact.
7. Include inversion/stress testing.
8. Produce a provisional conclusion or explain why one is not yet justified.
9. Produce a next action.
10. Produce a copy-ready next prompt.
11. Recommend whether to preserve the artifact in local artifact memory.

Proposed deliverables

Keep the first implementation small but complete.

Required files:

docs/INSIGHT_SURFACE_LOOP.md
patterns/22-insight-surface-loop.md
commands/think-with-me-about.md
examples/think-with-me-about.example.html

Optional only if useful and low-risk:

templates/think-with-me-about.html
checklists/insight-surface-loop.md
examples/think-with-me-about.metadata.example.json

Do not add the optional files if they make the first PR too heavy.

HTML artifact requirements

The artifact should be a thinking surface, not a report.

It should include these zones:

North Star

• topic;
• real question;
• desired decision or insight;
• provisional conclusion;
• confidence;
• next action.

Evidence Board

• facts;
• evidence;
• constraints;
• unknowns;
• freshness risk.

Perspective Map

• perspectives;
• alternatives;
• stakeholders;
• hidden options;
• second-order effects.

Tension Map

• contradictions;
• trade-offs;
• risks;
• weakest assumptions;
• what could change the conclusion.

Inversion Panel

• how this fails;
• what to avoid;
• what would make the idea fragile;
• what would make the conclusion wrong.

Insight Card

• strongest insight;
• provisional conclusion;
• confidence;
• why it matters;
• what changed in the user's understanding.

Action Queue

• do now;
• test next;
• investigate;
• stop doing;
• defer or discard.

Preserve / Re-enter

• archive recommendation;
• suggested artifact memory class;
• suggested tags;
• next prompt;
• follow-up question.

KISS constraints

The first version should be powerful because it is clear, not because it is complex.

Do:

• use one self-contained HTML file;
• keep interaction minimal;
• prioritize first-screen clarity;
• produce one strong next action;
• produce one strong next prompt;
• include only useful sections;
• use plain language;
• keep visual hierarchy calm and readable.

Do not:

• build a full note-taking app;
• build a mind-mapping app;
• add a database;
• add cloud sync;
• add heavy JavaScript;
• add model selection;
• add academic theory overload;
• add decorative charts;
• create a huge generic dashboard;
• make the user fill a long form.

Anti-slop rules

The artifact must not:

• pretend certainty without evidence;
• invent facts, sources, metrics, or confidence;
• produce generic insight like "consider the pros and cons";
• hide assumptions;
• skip inversion;
• end without action;
• end without a next prompt;
• show complex visuals that do not change the thinking;
• save low-value thinking into artifact memory by default;
• use HTML if Markdown is clearly enough.

P0 acceptance criteria

The PR must pass these or it should not be merged:

• Adds /think-with-me-about command.
• Documents the Insight Surface Loop.
• Adds pattern 22-insight-surface-loop or an equivalent pattern file.
• Adds one self-contained HTML example.
• The example moves from unclear topic to provisional conclusion.
• The artifact separates facts, inferences, assumptions, hypotheses, and unknowns.
• The artifact includes inversion/stress testing.
• The artifact includes next action and next prompt.
• The artifact includes archive recommendation.
• No installer behavior is changed unless explicitly justified.
• No external dependencies are added.

P1 acceptance criteria

• The first screen makes the thinking state obvious.
• The method uses at least two thinking lenses without turning the artifact into theory notes.
• The example shows why HTML beats Markdown.
• The command explains when not to use HTML.
• The artifact memory classification is compatible with docs/ARTIFACT_MEMORY.md.
• The next prompt preserves context for a second cycle.

P2 polish

• Add copy button for next prompt.
• Add optional filters or toggles only if they reduce cognitive load.
• Add a minimal metadata example.
• Add a checklist if it helps future validation.
• Add responsive behavior for mobile.

Example scenario for the demo

Use a topic aligned with the repo so the demo is credible:

How can html-explainer help users think through complex ideas and reach better conclusions faster?

The demo should show:

• initial ambiguity;
• perspective expansion;
• evidence/assumptions split;
• risks and inversion;
• emerging insight;
• provisional conclusion;
• next action;
• next prompt;
• archive recommendation.

Integration with existing repo power

This feature should compose with the existing repo, not bypass it.

Use or reference:

• docs/DECISION_GATE.md for whether HTML is justified;
• docs/PATTERN_GUIDE.md for routing context;
• docs/FACT_SHEET.md for evidence discipline;
• docs/QUALITY_BAR.md for artifact quality;
• docs/CHAIN.md for next prompt and continuation;
• docs/DELIVERY.md for output expectations;
• docs/ARTIFACT_MEMORY.md for preservation;
• docs/ACTIONABLE_KNOWLEDGE_BASE.md for future re-entry;
• issue Extract high-value design workflow patterns from nexu-io/open-design #9 concepts for discovery, modes, anti-slop, and P0/P1/P2 gates if available.

Verification

• Open the example HTML locally.
• Confirm no external network dependency exists.
• Confirm it is readable on desktop and narrow screen.
• Confirm the next prompt can be copied or clearly selected.
• Confirm the command file points to the method and required checks.
• Run existing validators:

scripts/validate-patterns.sh
scripts/validate-commands.sh
scripts/validate-examples.sh

If adding pattern 22 requires updating validators that currently expect exactly 21 patterns, update them deliberately and minimally.

Success definition

This issue succeeds when html-explainer gains a low-friction way to help users think better, not just explain better.

The ideal result:

unclear idea -> visual thinking surface -> evidence and assumptions -> tension and inversion -> provisional insight -> action -> next prompt -> reusable local knowledge

The first version should feel simple to use and strong enough to reveal conclusions the user might not have reached as quickly in plain chat or Markdown.

[ramsani]

Completed in main. Added /think-with-me-about, docs/INSIGHT_SURFACE_LOOP.md, patterns/22-insight-surface-loop.md, and examples/think-with-me-about.example.html. The example was corrected and passes local semantic validation.