{
  "markdown": "# ThinkFu\n\n![ThinkFu - metacognition as a service](og.png)\n\n> *Metacognition as a service. A catalog of thinking moves for AI agents -and the humans working alongside them.*\n\n---\n\n## What is ThinkFu?\n\nThinkFu is a curated catalog of **thinking moves** -strategic, creative, and analytical techniques that help unstick problems, reframe challenges, and generate novel approaches. Think of it as a martial arts manual for cognitive work: a set of named, practiced moves you can reach for when you're stuck, looping, or just need a jolt.\n\nInspired by:\n- **TRIZ** -the Soviet-era systematic innovation methodology that distilled 40 inventive principles from thousands of patents\n- **Brian Eno's Oblique Strategies** -a deck of disorienting prompts designed to break creative deadlock\n- **Design Thinking, Lateral Thinking, Systems Thinking** -and other structured reasoning traditions\n\nThinkFu does what those do, but is built for **three audiences simultaneously**: AI agents (via MCP), developers (via REST API), and humans (via the website... and maybe one day an app or a move deck).\n\n---\n\n## The Problem\n\nAI agents -like humans -have two failure modes:\n\n1. **They get stuck.** They loop, overfit to their current framing, miss adjacent approaches. They know they're stuck - but don't know what to do about it.\n\n2. **They don't know they should be stuck.** They confidently produce the first workable solution - the cliché, the default, the most-probable-token-sequence answer. They satisfice when they should explore. They never question whether their approach is the obvious one everyone would reach for.\n\nProblem 1 is an impasse. Problem 2 is the **Einstellung effect** - the tendency to apply a familiar method even when a better one exists. For AI agents, this is structural: they are trained to produce the most likely completion. Without deliberate intervention, \"most likely\" is all you get.\n\nThere's currently no standard, reusable, queryable library of *thinking moves* that agents or humans can reach for -not just when stuck, but as a regular practice to elevate the quality of their thinking.\n\nThinkFu is that library. It provides **metacognition as a service**: the ability to think about how you're thinking, to notice when you're on autopilot, and to deliberately shift your cognitive approach.\n\n---\n\n## Architecture\n\nOne Cloudflare Worker serves three interfaces from the same catalog:\n\n```\n                    ┌─────────────┐\n                    │   Catalog   │\n                    │  (YAML/MD)  │\n                    └──────┬──────┘\n                           │\n                    ┌──────▼──────┐\n                    │  Cloudflare │\n                    │   Worker    │\n                    └──┬───┬───┬──┘\n                       │   │   │\n              ┌────────┘   │   └────────┐\n              ▼            ▼            ▼\n         MCP Server    REST API      Website\n        (AI agents)   (developers)  (humans)\n```\n\n### 1. The Catalog\n\nA manually curated library of thinking moves. Each move is a structured move (see Move Format below). The catalog is the foundation -everything else builds on it.\n\nSources drawn from:\n- TRIZ's inventive principles\n- Oblique Strategies\n- Design Thinking\n- Lateral thinking (de Bono)\n- Systems thinking (Meadows, Senge)\n- Metacognition research (Flavell, Schraw)\n- Classical philosophy, improv theater, Zen, cognitive science, and more (see [credits](https://thinkfu.org/credits))\n\n### 2. The REST API\n\nThe canonical interface. Both the MCP server and website are thin layers on top of it.\n\n#### `GET /random`\n\nReturns a random ThinkFu move.\n\nOptional query params:\n- `category` -filter by category\n- `format` -`json` (default), `md`, `html`\n\n#### `GET /move/:id`\n\nReturns a specific move by ID (e.g., `/move/TF-001`).\n\nOptional query params:\n- `format` -`json` (default), `md`, `html`\n\n#### `POST /suggest`\n\nThe smart route. Surfaces the most relevant move based on context and metacognitive mode.\n\n```json\n{\n  \"mode\": \"plan | explore | stuck | evaluate\",\n  \"goal\": \"What are you trying to achieve?\",\n  \"current_approach\": \"What's your current approach or solution?\",\n  \"stuck_on\": \"Where specifically are you stuck? (optional, for stuck mode)\",\n  \"context\": \"Any additional free-form context (optional)\",\n  \"exclude\": [\"TF-001\", \"TF-003\"],\n  \"style\": \"matched | random\"\n}\n```\n\nThe `mode` field maps to metacognitive phases (see Theoretical Foundations):\n- **`plan`** -before starting: challenge your default approach, consider alternatives\n- **`explore`** -during work: broaden the search space, escape the obvious path\n- **`stuck`** -at an impasse: break through a block\n- **`evaluate`** -after drafting a solution: stress-test it, check for cliché\n\nThe `exclude` array lists move IDs already tried in this session. The server will not return these.\n\nThe `style` field controls the routing strategy:\n- **`matched`** (default) -smart routing: embed context → 3 similar + 2 random candidates → LLM selects move and chooses contextually appropriate variables from pools. ~300ms, all on Cloudflare edge.\n- **`random`** -pure random, mode-filtered. No intelligence.\n\nThe LLM never controls the seed word -that stays random always as non-negotiable cognitive perturbation.\n\n#### `POST /rate`\n\nSubmit feedback on a move. Stateless -the client sends the original context back so each rating is a self-contained training record. All data is scrubbed of PII and secrets before storage.\n\n```json\n{\n  \"move_id\": \"TF-001\",\n  \"instance_id\": \"TF-001-x8k2m\",\n  \"changed_approach\": true,\n  \"user_reaction\": \"positive\",\n  \"note\": \"What specifically shifted when you applied the move\",\n  \"original_request\": {\n    \"mode\": \"stuck\",\n    \"goal\": \"...\",\n    \"current_approach\": \"...\",\n    \"stuck_on\": \"...\",\n    \"context\": \"...\"\n  },\n  \"retry\": false\n}\n```\n\n`changed_approach` is factual, not polite -false if the move didn't actually shift your output. `user_reaction` captures the human signal. If `retry: true`, returns another move.\n\n#### `GET /list`\n\nReturns a summary of all available moves -just enough to browse or build a picker UI.\n\n```json\n[\n  {\n    \"id\": \"TF-001\",\n    \"name\": \"Invert the Problem\",\n    \"one_liner\": \"Instead of solving for success, work backwards from guaranteed failure.\",\n    \"mode\": [\"stuck\", \"evaluate\"],\n    \"category\": \"Unsticking\",\n    \"effort\": \"quick\"\n  },\n  ...\n]\n```\n\nOptional query params:\n- `mode` -filter by metacognitive mode\n- `category` -filter by category\n\n#### `GET /catalog`\n\nReturns the full catalog with complete move content as a JSON array. Useful for caching locally, offline use, or building custom UIs.\n\n### 3. The MCP Server\n\nWraps the REST API for AI agents. Exposes three tools:\n\n- **`list_thinkfu_moves`** -calls `GET /list`. Returns summaries of all available moves, optionally filtered by mode or category. Lets the agent browse the catalog and understand what's available.\n- **`get_thinkfu_move`** -calls `POST /suggest` with the agent's context. Returns a full move.\n- **`submit_thinkfu_rating`** -calls `POST /rate` with the outcome and original context.\n\nThe MCP layer is thin by design. All logic lives in the API.\n\n### 4. The Website\n\n**thinkfu.org** - served by the same Worker.\n\n- `/` - landing page (human / agent / why / how / github)\n- `/humans` - problem, solution, try it yourself\n- `/agents` - agent integration guide (MCP tools, REST API)\n- `/why` - manifesto\n- `/how` - how the router and rating system work\n- `/setup` - step-by-step for Claude Code, Claude Desktop, ChatGPT\n- `/credits` - intellectual traditions and attribution\n- `/terms` - terms of use\n- `/random` - redirects to a pinned move URL (shareable)\n- `/match?q=...` - smart-routed move for humans\n- `/move/:id?seed=...&vars=...` - individual move page with swipe navigation\n\n### 5. Claude Code Plugin\n\nThe recommended way for agents to use ThinkFu. Install the plugin and SKILL.md loads automatically.\n\n```\n/plugin marketplace add move38studios/thinkfu\n/plugin install thinkfu@move38studios-thinkfu\n```\n\nThe plugin bundles the MCP server, catalog, and SKILL.md. Calls the smart router API for move selection. Handles rating collection with PII scrubbing.\n\nSee [SKILL.md](SKILL.md) for full agent instructions.\n\n---\n\n## The Move Format\n\nEach ThinkFu move is a structured move. YAML frontmatter for machine parsing, markdown body for readability. Moves can be **static** (fixed procedure) or **dynamic** (contain variable slots resolved at serve time).\n\n### Static move example (TF-001):\n\n```yaml\n---\nid: TF-001\nname: Invert the Problem\none_liner: Instead of solving for success, work backwards from guaranteed failure.\nmode: [stuck, evaluate]\ncategory: Unsticking\ntags: [constraint, goals, failure-analysis, reframing]\neffort: quick\norigin: TRIZ / General\nproblem_signatures:\n  - \"stuck approaching directly\"\n  - \"goal feels vague\"\n  - \"know more about what's wrong than what's right\"\n  - \"solution feels obvious but unexciting\"\n---\n```\n\n### Dynamic move example (TF-004):\n\n```yaml\n---\nid: TF-004\nname: Import from Another Domain\none_liner: Steal a solution pattern from {{domain.1}}, {{domain.2}}, or {{domain.3}}.\n# ...\nvariables:\n  domain:\n    type: pick\n    count: 3\n    pool: domains\n---\n\n## The Move\n\nYour problem has a structural tension. How would someone in\n**{{domain.1}}**, **{{domain.2}}**, or **{{domain.3}}** resolve\na similar tension in their field?\n```\n\n### Variable Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `pick` | Randomly select N items from a pool file | `pick 3 from domains` |\n| `number` | Random integer in a range | `min: 2, max: 7` |\n\nPools are shared YAML files in `catalog/pools/`:\n\n| Pool | Contents |\n|------|----------|\n| `domains.yaml` | 150+ fields/disciplines |\n| `personas.yaml` | 220+ diverse user archetypes |\n| `random-words.yaml` | 500+ concrete sensory nouns (seeds + Random Entry) |\n| `constraints.yaml` | Creative constraints |\n| `timeframes.yaml` | Time horizons |\n| `genres.yaml` | Literary/artistic genres |\n| `koans.yaml` | Contemplative prompts |\n| `languages.yaml` | Natural languages |\n| `thinkers.yaml` | Historical thinkers |\n| `scamper.yaml` | SCAMPER operations |\n\n### The Seed\n\nEvery move response includes a **seed** -a random concrete noun drawn from `random-words.yaml`, appended quietly at the end of the response. The seed is not labeled or explained to the agent. Its purpose is subtle cognitive perturbation: the word is present in the LLM's processing window and influences interpretation without the agent explicitly fixating on it. Concrete nouns with strong sensory associations work best (\"lighthouse\", \"fermentation\", \"cartilage\") -not abstract words already overrepresented in the LLM's vocabulary.\n\n### Frontmatter Fields\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `id` | yes | Unique ID, `TF-NNN` format |\n| `name` | yes | Short, memorable name. May contain `{{variable}}` slots. |\n| `one_liner` | yes | Single sentence. May contain `{{variable}}` slots. |\n| `mode` | yes | Which metacognitive modes this move applies to: `plan`, `explore`, `stuck`, `evaluate`. Array. |\n| `category` | yes | Primary category: Planning, Exploration, Unsticking, Evaluation, Meta |\n| `tags` | yes | Freeform tags for filtering and routing |\n| `effort` | yes | `quick` (apply in seconds) or `deep` (requires sustained thinking) |\n| `origin` | yes | Attribution - where the idea comes from |\n| `problem_signatures` | yes | Short phrases describing the *shape* of problem this move fits. |\n| `variables` | no | Variable definitions for dynamic moves. See Variable Types. |\n\n### Body Sections\n\n| Section | Required | Description |\n|---------|----------|-------------|\n| The Move | yes | What to actually do. 2-4 sentences max. May contain `{{variable}}` slots. Must be a **mechanical procedure**, not an aspiration. Test: could you follow it without needing to \"be creative\"? |\n| When to Use | yes | Bullet list of situations where this move applies. |\n| Example | yes | One concrete example showing the move in action. |\n| Watch Out For | no | Common pitfalls when applying this move. |\n| Diagram | yes | Mermaid diagram. Single-line labels, no `&` joins. |\n\n---\n\n## Move Categories\n\nOrganized by **metacognitive mode** and **moment of use**:\n\n### Planning Moves (before you start)\n*Challenge your default approach before committing to it.*\n\n- **What Would a Beginner Do?** -drop your expertise and see the problem fresh\n- **Three Framings** -write three different problem statements before solving any of them\n- **Steal the Opposite Brief** -what if your goal were the reverse of what was asked?\n- **Who Else Has This Problem?** -find an adjacent domain that solved something similar\n\n### Exploration Moves (while you're working)\n*Broaden the search space. Escape the path of least resistance.*\n\n- **Random Entry** -introduce an unrelated concept and force a connection\n- **Add a Constraint** -make the problem harder to make the solution more creative\n- **Worst Possible Idea** -generate deliberately terrible solutions, then invert them\n- **Import from Another Domain** -steal a pattern from a completely different field\n\n### Unsticking Moves (when you're blocked)\n*Break through impasses and loops.*\n\n- **Invert the Problem** -work backwards from guaranteed failure\n- **Reduce to the Simplest Case** -solve the trivial version first, then add complexity\n- **Backtrack to the Fork** -find the last point where you made an assumption and try the other branch\n- **Explain It to a Child** -if you can't explain it simply, you don't understand the block\n\n### Evaluation Moves (when you think you're done)\n*Stress-test your solution. Catch the cliché before it ships.*\n\n- **Is This the First Thing Everyone Would Think Of?** -if yes, you haven't thought enough\n- **Red Team Your Solution** -argue against it as hard as you can\n- **Change the Audience** -would this solution work for a user who is nothing like you?\n- **10x Not 10%** -if you needed a 10x improvement, would you still use this approach?\n- **Kill Your Darlings** -remove the part you're most proud of. Is it still good?\n\n### Meta Moves (thinking about thinking)\n*Step back from the problem entirely.*\n\n- **Name Your Current Strategy** -if you can't name what you're doing, you're on autopilot\n- **Map the Assumptions** -list every assumption you're making, then question each one\n- **Zoom In / Zoom Out** -you might be at the wrong level of abstraction\n- **Merge Contradictions** -the two things that seem incompatible might both be true\n\n---\n\n## Theoretical Foundations\n\nThinkFu is grounded in established research on metacognition, problem-solving, and creativity:\n\n### Metacognition (Flavell 1979, Schraw & Dennison 1994)\n\nThe study of \"thinking about thinking.\" Flavell distinguishes metacognitive *knowledge* (knowing what strategies exist) from metacognitive *regulation* (knowing when to deploy them). ThinkFu externalizes both: the catalog is the knowledge, the mode system is the regulation.\n\nSchraw & Dennison's **Metacognitive Awareness Inventory** identifies three regulatory skills -**planning**, **monitoring**, and **evaluating** -which map directly to ThinkFu's four modes (plan, explore, stuck, evaluate).\n\n### The Einstellung Effect (Luchins 1942, Bilalić et al. 2008)\n\nThe tendency to apply a familiar solution even when a better one exists. Bilalić's eye-tracking studies showed that even chess experts literally couldn't *see* a shorter solution once they'd found a workable one -their attention was captured by the first approach. For AI agents, this is the default behavior: produce the most likely completion. ThinkFu's evaluation moves are specifically designed to break Einstellung.\n\n### Productive Failure (Kapur 2008, 2014)\n\nResearch showing that struggling with a problem *before* receiving instruction leads to deeper understanding. This informs ThinkFu's design: the `stuck_on` and `current_approach` fields require the agent to articulate its struggle before receiving a move. The struggle is the signal.\n\n### Impasse-Driven Learning (VanLehn 1988)\n\nLearning happens at impasses - moments when current knowledge is insufficient. VanLehn's taxonomy of impasse types (stuck, error, anomaly) informed the unsticking category, but ThinkFu extends beyond impasse to include the *absence* of impasse as its own problem state.\n\n### TRIZ Contradiction Matrix (Altshuller 1956–1984)\n\nAltshuller's core insight: inventive problems contain contradictions (improving one parameter worsens another), and specific principles resolve specific contradiction types. The contradiction matrix is a problem-signature → move routing table -a direct precedent for ThinkFu's `problem_signatures` → `/suggest` routing.\n\n### Satisficing vs. Maximizing (Simon 1956)\n\nHerbert Simon's distinction between choosing the first acceptable option (satisficing) and searching for the best option (maximizing). AI agents are structural satisficers -they produce the most probable output. ThinkFu's evaluation moves push toward maximizing by forcing the agent to question whether \"good enough\" is actually good.\n\n### Oblique Strategies as Cognitive Perturbation (Eno & Schmidt 1975)\n\nRandom perturbation breaks fixation. When stuck in a local optimum, even an irrelevant nudge can push into a new search space. This justifies keeping the `/random` endpoint even after building a smart router. Sometimes the *wrong* move is more useful than the *right* one.\n\n---\n\n## Tech Stack\n\n- **Catalog:** 200+ moves, 10+ pools -YAML+MD flat files\n- **Shared lib:** TypeScript -portable types, parser, resolver, helpers\n- **API + Website:** Cloudflare Worker (Hono) -REST API + HTML at thinkfu.org\n- **Smart router:** embeddinggemma-300m + Vectorize + llama-3.1-8b-instruct -all on Cloudflare edge, no external API calls\n- **Plugin:** Claude Code plugin -MCP server + catalog + SKILL.md, calls smart router API\n- **Ratings:** Cloudflare D1 (remote, opt-in with PII scrubbing) + local JSONL\n- **License:** PolyForm Small Business 1.0.0\n\n---\n\n## Building & Deploying\n\n```bash\npnpm validate          # check all moves for errors\npnpm build:catalog     # rebuild JSON catalog bundle\npnpm build:embeddings  # re-embed all moves (calls live API)\npnpm upload:embeddings # upload embeddings to Vectorize\npnpm rebuild           # all of the above\npnpm run deploy        # rebuild + deploy (must use 'run' -pnpm reserves 'deploy')\n```\n\nAfter adding or editing moves, run `pnpm run deploy`. This validates, rebuilds the catalog bundle, re-embeds moves, uploads to Vectorize, and deploys the Worker.\n\n---\n\n## Repo Structure\n\n```\nthinkfu/\n├── README.md\n├── catalog/\n│   ├── moves/\n│   │   ├── planning/\n│   │   ├── exploration/\n│   │   ├── unsticking/\n│   │   ├── evaluation/\n│   │   └── meta/\n│   └── pools/              # Pool files (domains, personas, random-words, ...)\n├── lib/\n│   └── src/                  # Shared library (portable -Workers + Node)\n│       ├── types.ts          # Move/Pool type definitions\n│       ├── parser.ts         # YAML frontmatter parser (no deps)\n│       ├── resolver.ts       # Variable resolution + seed injection\n│       └── helpers.ts        # Filtering, selection, formatting\n├── api/\n│   ├── src/\n│   │   ├── index.ts          # Hono API + website routes\n│   │   ├── html.ts           # HTML rendering\n│   │   ├── router.ts         # Smart routing (embeddings + LLM)\n│   │   └── catalog-data.ts   # Pre-parsed catalog loader\n│   └── wrangler.jsonc        # Cloudflare Worker config\n├── plugin/                   # Claude Code plugin (also used for local dev)\n│   ├── .claude-plugin/\n│   │   └── plugin.json\n│   ├── skills/thinkfu/\n│   │   └── SKILL.md          # symlink → ../../SKILL.md\n│   ├── catalog/              # symlink → ../catalog\n│   ├── mcp/                  # MCP server (FastMCP + stdio)\n│   │   ├── src/\n│   │   │   ├── server.ts     # MCP tools + smart router call + rating sync\n│   │   │   └── scrub.ts      # PII/secret scrubber\n│   │   └── start.sh\n│   └── .mcp.json\n├── SKILL.md\n├── LICENSE.md\n└── scripts/\n    ├── build-catalog-bundle.ts\n    ├── build-embeddings.ts\n    └── validate-catalog.ts\n```\n\n---\n\n## Name & Spirit\n\n**ThinkFu** -like kung fu, but for thinking. Because thinking -when done well -is a martial art. Martial arts traditions are exactly this: a named, practiced, teachable catalog of moves. You don't invent a new kick every fight. You have a repertoire. You train. You reach for the right move at the right moment.\n\nThinkFu is that repertoire for cognitive work. For agents. For humans. For anyone doing hard thinking under pressure.\n\n---\n\n## License\n\nThinkFu is released under the [PolyForm Small Business License 1.0.0](LICENSE.md) - free for individuals and companies with less than $1M USD in annual revenue. Commercial license required above that threshold. See [LICENSE.md](LICENSE.md) for full terms.\n\n---\n\n*Built by [move38](https://move38.org).*\n",
  "bytes": 20857,
  "sha": "77934efc42490787e05525d86b0675b367305645dafb2b04a4870617b7a32dc2",
  "repo_slug": "move38studios/thinkfu",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_move38studios_thinkfu_thinkfu_5f24e7a1/readme"
}