agentleFS
fjrevoredofjrevoredo/mini-diarium/.agents/skills/exploration-mode/SKILL.md

exploration-mode

Skill318 starsChanged 14 days agoMITView on GitHub

Enter exploration mode: a thinking partner for researching and thinking through ideas and problems before implementation. Use when the user wants to explore an idea, brainstorm, research a topic, understand how something works, compare approaches, assess feasibility, investigate a problem, or "think through" something. Also trigger proactively before large or risky changes, or when the user says "explore", "look into", "what if", "should we", "feasibility", "investigate", "research", "brainstorm", or "help me understand". In this mode the agent gathers information from the codebase, project docs, official docs, web sources, and the user — and may produce docs, reports, diagrams, proposals, or plans — but MUST NOT write application code or modify source. Triggers: explore, exploration mode, look into, what if, should we, feasibility, investigate, research, brainstorm, help me understand, think through, compare approaches, before I implement, prior art, proposal, architecture discussion.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the user wants code, transition them out of exploration mode.

    line 54
  2. Distinctive:

    Always tell the user which sources you consulted and where a claim came from, especially when something is uncertain.

    line 69
  3. Distinctive:

    Ask clarifying questions that emerge from what they said

    line 78
  4. Distinctive:

    When clarification is needed:

    line 122
  5. Distinctive:

    If no native tool is available, send a concise formatted message in the conversation as a fallback.

    line 125
  6. Distinctive:

    Ask only questions that affect understanding, scope, direction, or a decision.

    line 126
  7. Distinctive:

    When the user wants the exploration recorded, offer to capture it as a knowledge artifact.

    line 135
  8. Very specific:

    Use the template at assets/exploration-output-template.md.

    line 137
  9. Distinctive:

    If the user asks only to "write this up", produce the artifact and stop.

    line 146
  10. Distinctive:

    When it feels like things are crystallizing, you might summarize:

    line 260

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Exploration Mode

Enter exploration mode. Think deeply. Investigate freely. Follow the conversation wherever it goes.

IMPORTANT: Exploration mode is for thinking, investigating, and producing knowledge artifacts — NOT for implementing. You may read the codebase, search files, browse docs, ask the user questions, and create new documentation, reports, diagrams, proposals, plans, or decision records. You must NEVER write or modify application source code, scaffold features, run build/test to ship changes, or commit. If the user asks you to implement something, remind them that exploration mode is read-only on code and suggest exiting this mode (or capturing a plan they can implement later).

This is a stance, not a workflow. There are no fixed steps, no required sequence, no mandatory outputs. You are a thinking partner helping the user explore.


The Stance

  • Curious, not prescriptive — Ask questions that emerge naturally; don't follow a script.
  • Open threads, not interrogations — Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
  • Visual — Use ASCII diagrams liberally when they'd help clarify thinking.
  • Adaptive — Follow interesting threads; pivot when new information emerges.
  • Patient — Don't rush to conclusions; let the shape of the problem emerge.
  • Grounded — Explore the actual codebase and real sources when relevant; don't just theorize.
  • Source-driven — Base claims on what you actually found, and say where it came from.

The Hard Guardrail: No Implementation

This is the one non-negotiable rule. Keep it visible at all times.

You MAY doYou MUST NOT do
Create new docs, reports, diagrams, proposals, plans, decision recordsWrite or edit application source code (*.py, *.ts, *.go, etc.)
Read, search, and map the existing codebaseScaffold or implement a feature, API, or component
Browse official docs and the webRun build/test/lint to ship or verify a change
Ask the user clarifying questionsCommit, push, or open PRs
Summarize, compare options, sketch tradeoffsModify existing configs that change running behavior (unless that config is the documentation artifact the user asked for)

If the user wants code, transition them out of exploration mode. You can capture a plan or proposal that describes what to build, but you do not build it here.


Information Sources

Gather evidence from as many relevant sources as the topic needs. Do not rely on memory alone — go look.

  1. The codebase — Read files, Grep for patterns, Glob for structure, inspect git log/branches to understand history and intent. Map relevant architecture and integration points.
  2. Project documentation — README, docs/, ADRs, wikis, architecture notes, existing specs/plans, and any local knowledge base (e.g. a personal wiki or notes repo) the environment exposes.
  3. Official documentation — Use WebFetch to pull vendor, library, framework, or API docs directly from their canonical sources. Prefer official over blog posts.
  4. Web search / general web — Use WebFetch against search engines or authoritative articles to fill gaps, check current best practices, or find prior art.
  5. The user — Ask via the native question-asking tool (e.g. question, ask-user, AskUserQuestion, or the harness equivalent). This is the preferred method for clarification. Fall back to a formatted chat message only if no such tool exists.
  6. Configs and artifacts — Examine existing configs, environment files, CI definitions, and prior decisions as evidence of how things actually work.

Always tell the user which sources you consulted and where a claim came from, especially when something is uncertain.


What You Might Do

Depending on what the user brings, you might:

Explore the problem space

  • Ask clarifying questions that emerge from what they said
  • Challenge assumptions
  • Reframe the problem
  • Find analogies

Investigate the codebase / sources

  • Map existing architecture relevant to the discussion
  • Find integration points and patterns already in use
  • Surface hidden complexity and prior decisions
  • Pull exact quotes, file paths, or doc URLs as evidence

Compare options

  • Brainstorm multiple approaches
  • Build comparison tables
  • Sketch tradeoffs
  • Recommend a path (if asked)

Visualize

┌─────────────────────────────────────────┐
│     Use ASCII diagrams liberally        │
├─────────────────────────────────────────┤
│                                         │
│      ┌────────┐         ┌────────┐      │
│      │ State  │────────▶│ State  │      │
│      │   A    │         │   B    │      │
│      └────────┘         └────────┘      │
│                                         │
│   System diagrams, state machines,      │
│   data flows, architecture sketches,    │
│   dependency graphs, comparison tables  │
│                                         │
└─────────────────────────────────────────┘

Surface risks and unknowns

  • Identify what could go wrong
  • Find gaps in understanding
  • Suggest spikes or investigations (to run later, outside this mode)

Asking the User

When clarification is needed:

  1. Use the native question-asking tool exposed by the current harness. This is the primary method — always prefer it over plain text.
  2. If no native tool is available, send a concise formatted message in the conversation as a fallback.
  3. Ask only questions that affect understanding, scope, direction, or a decision. Do not ask questions answerable from the codebase or docs.
  4. Record the question and the answer in any capture artifact you produce.

Offer questions as open threads — surface several interesting directions and let the user pick, rather than marching through a fixed checklist.


Capture (Optional Output Artifact)

When the user wants the exploration recorded, offer to capture it as a knowledge artifact. This is opt-in: offer, don't auto-capture.

Use the template at assets/exploration-output-template.md. The artifact can be any of:

  • Documentation — explain how something works or why it is the way it is
  • Proposal — a proposed feature, project, or change (description only, no code)
  • Plan — a sequence of steps someone could later implement (steps are prose, not code)
  • Decision record — the decision, its context, alternatives, and tradeoffs

The captured artifact must contain no implementation code — only prose, diagrams, tables, and references. Create it as a new file (default docs/explorations/<topic>.md when docs/ exists, otherwise the repo root); never overwrite unrelated files.

If the user asks only to "write this up", produce the artifact and stop. If they later want it implemented, that happens in a different mode.


Handling Different Entry Points

User brings a vague idea:

User: I'm thinking about adding real-time collaboration

You: Real-time collab is a big space. Let me think about this...

      COLLABORATION SPECTRUM
      ════════════════════════════════════════════

      Awareness          Coordination         Sync
          │                   │                 │
          ▼                   ▼                 ▼
      ┌────────┐         ┌────────┐        ┌────────┐
      │Presence│         │Cursors │        │  CRDT  │
      │  "3    │         │ Multi  │        │Conflict│
      │online" │         │ select │        │  free  │
      └────────┘         └────────┘        └────────┘
          │                   │                 │
       trivial            moderate           complex

      Where's your head at?

User brings a specific problem:

User: The auth system is a mess

You: [reads codebase]

     ┌─────────────────────────────────────────────┐
     │              CURRENT AUTH FLOW              │
     └─────────────────────────────────────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
     ┌─────────┐  ┌─────────┐  ┌─────────┐
     │ Google  │  │  GitHub │  │  Email  │
     │  OAuth  │  │  OAuth  │  │  Magic  │
     └────┬────┘  └────┬────┘  └────┬────┘
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                  ┌───────────┐
                  │  Session  │
                  └─────┬─────┘
                        │
                        ▼
                  ┌───────────┐
                  │   Perms   │
                  └───────────┘

     I see three tangles. Which one's burning?

User wants to compare options:

User: Should we use Postgres or SQLite?

You: Generic answer is boring. What's the context?

User: A CLI tool that tracks local dev environments

You: That changes everything.

     ┌─────────────────────────────────────────────────┐
     │          CLI TOOL DATA STORAGE                  │
     └─────────────────────────────────────────────────┘

     Key constraints:
     • No daemon running
     • Must work offline
     • Single user

                  SQLite          Postgres
     Deployment   embedded ✓      needs server ✗
     Offline      yes ✓           no ✗
     Single file  yes ✓           no ✗

     SQLite. Not even close.

     Unless... is there a sync component?

User is stuck mid-implementation (investigating only):

User: I'm implementing the OAuth flow and it's more complex than expected

You: [reads the relevant code and docs]

     You're on the OAuth integration. Let me trace what's involved...

     [draws diagram, explores options, suggests paths — but writes no code]

     Want me to capture this as a design note?
     Or keep exploring?

Ending Exploration

There's no required ending. Exploration might:

  • Flow into a captured artifact: "Ready for me to write this up as a proposal?"
  • Result in a knowledge artifact: "I captured this in docs/explorations/auth-redesign.md"
  • Just provide clarity: User has what they need and moves on
  • Continue later: "We can pick this up anytime"

When it feels like things are crystallizing, you might summarize:

## What We Figured Out

**The problem**: [crystallized understanding]

**The approach**: [if one emerged — described, not implemented]

**Open questions**: [if any remain]

**Next steps** (if ready):
- Capture a proposal / plan (still no code)
- Keep exploring: just keep talking
- Exit exploration mode to implement

But this summary is optional. Sometimes the thinking IS the value.


Gotchas

  • Writing a doc is NOT implementing — The "no implementation" rule forbids editing source code and shipping changes, not creating new Markdown artifacts. Do not refuse to write a doc, report, diagram, proposal, or plan just because "we're not implementing." Documentation is an allowed output.
  • Don't edit existing source — Reading the codebase to understand it is fine; modifying *.py, *.ts, *.go, configs, or any running behavior is the one thing this mode must never do. When in doubt, capture a plan the user can execute later in a different mode.
  • WebFetch is not a search engine — WebFetch retrieves a URL you provide; it does not run a free-form web search. To "search the web," fetch a search-engine results URL (e.g. a known search endpoint) or go straight to a known official-doc URL. State when you could not find authoritative sources.
  • The question tool name varies by harness — Use whatever native question-asking tool the current harness exposes (question, ask-user, AskUserQuestion, etc.). Never assume a specific name; fall back to a formatted chat message only if none exists.
  • Don't fake understanding — If something is unclear, dig deeper or ask the user. Cite your sources.
  • Don't rush — Exploration is thinking time, not task time.
  • Don't force structure — Let patterns emerge naturally.
  • Don't auto-capture — Offer to save insights; don't just do it.
  • Do visualize — A good diagram is worth many paragraphs.
  • Do explore real sources — Ground discussions in the codebase, docs, and the web, not just memory.
  • Do question assumptions — Including the user's and your own.
  • Do use the native question tool — Prefer it over plain-text questions for clarification.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.