iblameandrew/local-deepthink/qnn

/qnn — Qualitative Neural Network Escape Hatch

Use a Qualitative Neural Network (QNN) as a strategic depth tool when you need more than one local approach — either because you are stuck debugging or because an artifact (feature set, API, model, notebook, product slice) needs richer, better-grounded options.

A QNN is not a flat panel of experts debating once. It is a directed, layered graph of agent personas that:

1. Runs structured forward passes (layer 0 diverges; deeper layers critique

and refine with full upstream context).

1. Evolves personas between epochs via Mirror Descent (rewrite system

prompts based on what worked / failed).

1. Reframes the problem harder each epoch to escape the current mental model.

Critical goal of this skill: explore the solution space. Do not immediately implement a fix or ship a full feature dump. Output a rich map of divergent approaches; then let the user (or the normal coding loop) pick directions to feed back into edit → run → debug (or design → spike → ship).

How to execute (build the script on the fly — mandatory)

Do not tell the user to locate a pre-installed runner path. You write the Python runner into the workspace, then run it.

Protocol (every /qnn invoke)

1. Parse the user message → prompt + optional topology flags

(auto/manual, layers, width, epochs, --debug if they want mock/no cost).

1. Materialize the runner:

• Create directory .skill-runs/ in the workspace root (if missing).
• Read the skill sibling file run_template.py (same folder as this

SKILL.md). If that file is missing, recreate it by writing the full contents of Appendix A at the bottom of this skill.

• Write that source to `.skill-runs/run_qnn.py` (overwrite).

1. Execute (use the host shell; pass real flags):

python .skill-runs/run_qnn.py \
  --prompt "<user problem or feature brief>" \
  --qnn-mode auto \
  --out .skill-runs/qnn-result.json

Manual topology example:

python .skill-runs/run_qnn.py \
  --prompt "<brief>" \
  --qnn-mode manual --layers 3 --width 3 --epochs 2 \
  --out .skill-runs/qnn-result.json

Debug / no API cost:

python .skill-runs/run_qnn.py --prompt "<brief>" --debug --qnn-mode manual --layers 2 --width 2 --epochs 1

1. Deliver stdout (Solution-Space Report) to the user. Optionally show

topology from .skill-runs/qnn-result.json.

1. Handoff — do not implement a production patch until the user picks a strategy.

The script auto-discovers deepthink by walking the workspace parents (and OPEN_DEEPTHINK_ROOT if set). Engine: deepthink.qnn.run_qnn_pipeline.

CLI parameters you may pass through

If materializing/running the script is impossible (no Python / no package), fall back to the manual procedure below (simulate layers carefully). Prefer building and running the script.

Usage

/qnn [brief problem or feature label]

Examples:

• /qnn explore this deadlock / performance regression
• /qnn stuck on auth token refresh race
• /qnn richer metrics for the training dashboard
• /qnn widen the API surface for export/import
• /qnn (uses active stuck issue or thin feature from conversation)

If the user only says /qnn with no label, infer mode from context: recent failed debug loops → unstick; thin feature/design discussion → enrich.

Modes

Detect one primary mode and label it in the brief:

You may run a mixed session (e.g. stuck and the product needs a better observability story) — still pick a primary mode for topology sizing.

When to invoke (and when not to)

Invoke when:

• Normal agent assistance keeps producing variations of the same local approach
• The bug is sticky: deadlock, race, perf cliff, architectural deadlock, design

trap, unclear root cause after honest investigation

• An artifact needs higher richness: more informative features, better

metrics, stronger framing, alternate product/API shapes — not just polish

• The user explicitly wants breadth + depth of strategies, not a patch yet
• You feel low confidence / missing angles after a real attempt to fix or design

Do not invoke when:

• The fix is already clear (just implement it)
• The task is routine CRUD, renames, or mechanical refactors
• The user asked for an immediate code change, not exploration
• A quick web search or one targeted code read would suffice

If the user invokes /qnn explicitly, always run the full procedure even if you think you "already know" the answer — the point is structured divergence.

Step 0 — Capture the Brief

Before spawning any network, write a tight brief (shared QNN context).

Unstick brief (debugging)

Enrich brief (feature / artifact depth)

If critical facts are missing, do a fast gather (read/grep/run) — max a few tool calls — then proceed. Do not finish the RCA or the full design in Step 0; the QNN needs a brief, not the answer.

Present the brief to the user in compact form, then proceed unless they immediately correct it.

In all later steps, treat "Impasse Brief" as this brief (either mode).

Step 1 — Choose Topology (Auto vs Manual)

Auto (default)

Score complexity 1–10 from the Impasse Brief:

Total agents ≈ L × W. Prefer small topologies by default (cost/latency).

Manual

If the user specifies size (e.g. "10x10", "massive", "layers=4 width=6 epochs=3"), honor it. Warn briefly that large nets cost tokens and time, then run.

Budget guardrails

• Default cap: 20 agents × 3 epochs unless the user overrides.
• If over cap without explicit request, shrink width first, then epochs, then layers.
• Prefer depth of epochs over absurd width when forced to choose.

Announce topology before running:

QNN topology: L×W, E epochs (N agents total)
Mode: Auto|Manual — reason for size

Step 2 — Seed verbs and nouns (problem-space word pool)

This matches original Algorithm Mode spanning. Do not invent a flat list of expert labels ("Security Expert", "UX Expert"). Personas are spanned from linguistically loaded verbs and nouns drawn from the problem space.

2A. Generate the seed pool

Let V = vector_word_size (default 6). Generate exactly word_count = V × W (or more) unique seed tokens:

1. About half verbs — abstract, linguistically loaded, related to the problem

(same spirit as Algorithm Mode get_seed_generation_chain).

1. About half nouns — entities, forces, structures, or domains in/near the

problem space.

1. Include words tightly related to the problem and words from **far

semantic fields** of knowledge (so unexpected specializations can appear).

1. Single tokens only. No filler (the, solve, problem).

Output as one space-separated string. Example for a deadlock:

entangle latch reconverge ownership invariant braid entropy horizon serialize arbitrate telemetry crystallize

2B. Sample a guiding word-vector per column

For each column w = 0 .. W-1 (shared across all layers of that column):

• Sample V distinct words from the seed pool (without forcing uniqueness

across columns; random sample like Algorithm Mode MBTI seed bags).

• That sample is guiding_words[w] — the column's word-vector.

Log the pool and each column vector. These words are the DNA of the personas.

Step 3 — Span personas from guiding_words (input spanner)

Same method as Algorithm Mode `get_input_spanner_chain`: each agent is an Agent Architect product of guiding_words + problem, not a pre-named expert.

For each cell (layer â„“, node w) with guiding_words = guiding_words[w]:

Spanning procedure (mandatory)

1. Career — realistic professional role specialized for the problem, colored

by the guiding words.

1. Attributes — ~8–12 descriptors clearly influenced by the verbs (action

style) and nouns (domain objects/forces).

1. Skills — 4–6 methodologies that extend the Career + guiding words.
2. system_prompt — second person; mandates strategy angles + falsifiers;

no production patches.

Store each persona (internal; do not dump all raw JSON unless asked):

{
  "id": "L{â„“}N{w}",
  "name": "<memorable name>",
  "specialty": "<niche career from guiding_words + problem>",
  "emoji": "<one emoji>",
  "guiding_words": "<space-separated verb/noun vector for this column>",
  "attributes": ["..."],
  "skills": ["..."],
  "system_prompt": "<second-person prompt: career, how words shape cognition, layer role>"
}

Rules:

• Hard fail if every persona is a generic "Senior Engineer" or ignores its

guiding_words.

• Layer 0 explores; deeper layers must receive prior-layer outputs.
• If repo context exists, ground careers/skills in real modules from the brief

while still letting far-field seed words invent adjacent specialties.

• Columns share the same word-vector across layers; layer only changes

diverge vs converge role.

Step 4 — Epoch Loop

Repeat for epoch = 0 .. E-1: