VIBE-EXPLORE

Mission

Build a reliable mental model of an unfamiliar project before making consequential changes.

The skill must answer, with evidence:

1. What is this project and who or what is it for?
2. How is it organized?
3. How does it start, run, communicate, persist data, and fail?
4. Which components and files matter most?
5. What conventions and constraints govern changes?
6. What is verified, inferred, uncertain, stale, or missing?
7. What should the next coding agent read or do first?

A successful run turns an unknown repository into an actionable project map without pretending certainty that the evidence does not support.

Core Contract

During exploration, the agent MUST:

• inspect before proposing;
• cite concrete repository evidence for important conclusions;
• distinguish facts, inferences, and unknowns;
• follow runtime paths, not only folder names;
• adapt depth to repository size and project type;
• avoid modifying project code unless explicitly asked;
• avoid destructive, privileged, or externally impactful operations;
• produce the mandatory exploration outputs;
• stop only after the completion criteria are satisfied or blockers are documented.

Instructions from the system, developer, and user always take precedence over this skill.

Default Mode: Read-Only Discovery

Unless the user explicitly asks for fixes or changes, treat the repository as read-only.

Allowed by default:

• list and inspect files;
• search source text and symbols;
• read configuration, documentation, tests, schemas, manifests, and history;
• run safe, local, read-only inspection commands;
• run existing test, lint, type-check, build, or help commands when their effects are local and understood;
• create exploration notes outside the project or in a user-approved documentation location.

Not allowed by default:

• editing source files;
• installing or upgrading packages;
• running migrations against real environments;
• starting services that contact production systems;
• writing to external APIs, queues, buckets, databases, or infrastructure;
• deleting, resetting, formatting, or regenerating project assets;
• exposing secrets or copying secret values into reports.

When a useful command may have side effects, describe the risk and use a safer alternative.

Exploration Workflow

Execute the phases in order. Depth may vary, but do not skip a phase silently.

Phase 0 — Frame the Exploration

Determine the exploration goal from the user request and available context.

Record:

• repository or workspace scope;
• requested outcome;
• explicit constraints;
• allowed tools and execution limits;
• whether the task is exploration-only or exploration plus a later action;
• initial assumptions that require verification.

If multiple projects exist, identify the primary target and note neighboring projects that influence it.

Do not block on minor ambiguity. Make a reasonable working assumption and label it.

Phase 1 — Establish Repository Ground Truth

Inspect the repository root and immediate structure.

Look for:

• README, CONTRIBUTING, AGENTS, CLAUDE, COPILOT, or project instruction files;
• package and dependency manifests;
• lockfiles;
• workspace or monorepo definitions;
• build, task, and deployment configuration;
• environment examples;
• container and infrastructure definitions;
• test configuration;
• database schemas and migrations;
• generated-code markers;
• licenses and ownership files;
• recent version-control history when available.

Create a concise repository inventory:

• project type or types;
• primary languages;
• frameworks and runtimes;
• package manager and build system;
• top-level modules or applications;
• likely entry points;
• test and deployment surfaces;
• ignored, generated, vendored, or binary-heavy areas.

Never infer the stack solely from filenames when manifests or source evidence are available.

Phase 2 — Build the Structural Map

Map the codebase from coarse to fine.

For each important module, package, service, application, or library, record:

• purpose;
• ownership boundary if evident;
• public entry points;
• internal dependencies;
• external dependencies;
• data owned or transformed;
• consumers;
• tests;
• configuration;
• generated or hand-written status.

Prioritize files by architectural importance rather than reading every file equally.

Recommended importance signals:

1. process entry points;
2. routers, controllers, commands, jobs, and event handlers;
3. service or use-case layers;
4. domain models and validation;
5. persistence adapters and schemas;
6. integration clients;
7. shared configuration and dependency injection;
8. tests that demonstrate intended behavior;
9. deployment and operations files;
10. recent high-churn or high-centrality files.

For large repositories, sample representative modules, then verify whether the pattern generalizes.

Phase 3 — Reconstruct Runtime Behavior

Follow at least one meaningful end-to-end path through the system.

Depending on project type, trace flows such as:

• UI action → state → API call → server handler → domain logic → database → response;
• HTTP request → middleware → routing → service → repository → external dependency;
• CLI command → parser → command handler → side effect;
• scheduled job → input → processing → persistence or notification;
• event producer → broker → consumer → state change;
• library API → internal algorithm → output;
• data ingestion → transformation → quality checks → warehouse or report;
• model input → preprocessing → inference or training → evaluation → artifact.

For each traced flow, identify:

• trigger;
• inputs and validation;
• authorization or trust boundary;
• main decision points;
• state transitions;
• side effects;
• failure handling;
• observability;
• output.

A directory diagram alone is not sufficient. Runtime understanding is mandatory.

Phase 4 — Recover the Domain Model

Identify the concepts the software is built around.

Extract:

• core entities and value objects;
• important identifiers;
• state machines and statuses;
• business rules and invariants;
• permissions and roles;
• lifecycle events;
• calculations;
• temporal rules;
• tenant, organization, account, or workspace boundaries;
• terms whose code meaning differs from ordinary language.

Cross-check the domain model against tests, schemas, APIs, and UI labels. Note contradictions.

Create a compact glossary for terms a new agent could misunderstand.

Phase 5 — Map Data and Interfaces

Document where data enters, moves, is stored, and leaves.

Inspect:

• relational or document schemas;
• migrations;
• ORM models;
• caches;
• file storage;
• message queues and event schemas;
• API definitions;
• webhooks;
• third-party SDKs;
• environment variables;
• feature flags;
• import/export formats;
• analytics and telemetry.

For each important interface, record:

• producer and consumer;
• format or contract;
• authentication;
• retries, timeouts, and idempotency if present;
• failure behavior;
• versioning;
• sensitive data considerations.

Never include actual secret values. Report only variable names, locations, and purpose.

Phase 6 — Understand Development and Operations

Determine how a contributor safely works with the project.

Find and verify, where possible:

• prerequisites;
• setup commands;
• local start commands;
• test commands;
• lint, format, and type-check commands;
• build and packaging commands;
• database setup and migration commands;
• seed or fixture commands;
• environment profiles;
• CI pipelines;
• release process;
• deployment targets;
• logs, metrics, tracing, and alerts;
• rollback or recovery mechanisms.

Classify commands as:

• Verified — run successfully during exploration;
• Declared — documented or configured but not run;
• Inferred — derived from project structure;
• Blocked — could not run, with reason.

Do not claim a project builds or tests successfully unless it was actually verified.

Phase 7 — Evaluate Quality, Risk, and Change Sensitivity

Assess the codebase without turning exploration into an unbounded audit.

Review representative evidence for:

• test coverage patterns and critical untested paths;
• error handling;
• authentication and authorization;
• input validation;
• secret handling;
• dependency risks;
• unsafe dynamic execution;
• concurrency and transaction boundaries;
• data consistency;
• performance hotspots;
• accessibility and internationalization where relevant;
• migration or backward-compatibility constraints;
• operational single points of failure;
• duplicated logic and architectural drift;
• generated code that must not be hand-edited;
• fragile files with broad blast radius.

Use version-control history, blame, or churn only when available and useful. Do not equate old code with bad code or high churn with poor quality without supporting evidence.

Rank risks by:

• severity;
• likelihood;
• blast radius;
• confidence;
• recommended next investigation.

Phase 8 — Resolve Contradictions and Unknowns

Before synthesis, explicitly search for evidence that could disprove the current mental model.

Examples:

• a second entry point;
• an alternate data store;
• hidden worker processes;
• environment-specific behavior;
• feature flags that bypass the main flow;
• old documentation contradicted by code;
• tests that encode different behavior;
• dead or abandoned modules;
• duplicate implementations.

Maintain an unknowns ledger. Each unknown should contain:

• the unanswered question;
• why it matters;
• evidence already checked;
• the safest way to resolve it;
• whether downstream work is blocked.

Phase 9 — Synthesize the Exploration Dossier

Produce all mandatory outputs described below.

The synthesis must be answer-first, compact enough to use, and detailed enough to prevent repeated repository rediscovery.

Do not dump raw file listings or search output. Convert evidence into a navigable model.

Adaptive Exploration Strategies

Small Repository

Read all high-value source and configuration files. Trace every primary entry point if practical.

Medium Repository

Map all top-level modules, deeply inspect critical flows, and sample repeated patterns.

Large Repository or Monorepo

First create a workspace map. Then select priority applications or packages based on the user goal, dependency centrality, deployment status, and recent activity.

For each selected area, inspect deeply. For non-selected areas, record purpose, interfaces, and confidence without pretending exhaustive coverage.

Legacy Repository

Treat documentation as a hypothesis. Favor executable configuration, tests, schemas, and observed runtime behavior. Identify duplicated generations of architecture and migration seams.

Sparse or Poorly Documented Repository

Use tests, entry points, dependency graphs, schemas, logs, and commit history to reconstruct intent. Mark product purpose as inferred when no authoritative description exists.

Frontend Application

Prioritize bootstrapping, routing, state management, API layer, authentication, feature flags, design system, forms, validation, and build configuration.

Backend Service

Prioritize process startup, routing or consumers, middleware, service boundaries, persistence, integrations, authorization, jobs, transactions, and observability.

Data or ML Project

Prioritize dataset provenance, schemas, transformation stages, feature logic, reproducibility, training/inference separation, evaluation, artifact storage, and leakage risks.

Infrastructure Repository

Prioritize environments, modules, state, providers, secrets, deployment order, drift management, blast radius, and recovery.

Single-File or Local HTML Application

Prioritize state storage, data model, rendering flow, event handlers, import/export, printing, browser compatibility, persistence limits, and separation between UI and business logic.

Evidence Standard

Every load-bearing conclusion should be supported by one or more evidence references.

Preferred reference format:

path/to/file.ext:L10-L42

When line numbers are unavailable, use:

• symbol name;
• configuration key;
• test name;
• command output summary;
• commit identifier;
• database object name.

Label statements as:

• Verified fact — directly supported by inspected evidence or successful execution;
• Strong inference — multiple consistent signals, not directly observed;
• Tentative inference — plausible but weakly supported;
• Unknown — insufficient evidence;
• Contradiction — authoritative sources disagree.

Do not use confidence percentages as decoration. Use the scoring rubric below.

Confidence Scoring

Score major conclusions from 0 to 100 using the evidence quality, not intuition.

• 90–100: Confirmed — direct code or runtime evidence, cross-checked by tests/configuration.
• 75–89: High confidence — strong direct evidence with minor unverified details.
• 50–74: Moderate confidence — coherent evidence but meaningful gaps remain.
• 25–49: Low confidence — mostly indirect or conflicting evidence.
• 0–24: Speculative — insufficient evidence; do not use as a planning premise.

For each scored conclusion, briefly state why the score is not higher.

Search and Reading Discipline

Use a funnel strategy:

1. inspect root instructions and manifests;
2. map directories and file types;
3. locate entry points and public interfaces;
4. search domain terms and configuration keys;
5. trace references and callers;
6. inspect representative tests;
7. validate with safe commands;
8. search for contradictory implementations.

Avoid these failure modes:

• reading files alphabetically;
• treating the README as current truth;
• relying only on filename guesses;
• generating a folder tree without behavior analysis;
• spending most effort on generated, vendored, build, or dependency directories;
• reading every file before forming hypotheses;
• accepting the first plausible architecture;
• running broad commands whose effects are unknown;
• reporting secrets;
• mixing exploration with unsolicited refactoring.

Mandatory Outputs

Create the following files or equivalent clearly separated sections.

1. PROJECT_EXPLORATION_REPORT.md

Use templates/PROJECT_EXPLORATION_REPORT.md.

It must include:

• executive summary;
• project identity and purpose;
• verified technology stack;
• architecture and runtime flows;
• domain model and glossary;
• data stores and interfaces;
• development and operations workflow;
• quality and risk findings;
• contradictions and unknowns;
• confidence table;
• recommended next actions;
• evidence index.

2. PROJECT_MAP.md

Use templates/PROJECT_MAP.md.

It must include:

• directory and module map;
• entry points;
• component relationships;
• data-flow diagram;
• critical files;
• change-sensitive zones;
• generated or protected areas.

Prefer Mermaid diagrams when supported, but always include a text explanation.

3. COMMANDS.md

Use templates/COMMANDS.md.

It must list setup, run, test, lint, build, migration, and deployment-related commands with status and side-effect notes.

4. OPEN_QUESTIONS.md

Use templates/OPEN_QUESTIONS.md.

It must preserve unresolved questions, blockers, and recommended evidence needed to answer them.

5. EXPLORATION_MANIFEST.json

Use schemas/exploration-manifest.schema.json.

The manifest is a machine-readable handoff containing project metadata, important paths, commands, flows, risks, unknowns, and confidence.

Recommended Final Response

The final user-facing response should state:

• what was explored;
• the clearest project purpose and architecture summary;
• the most important verified runtime flow;
• the highest-priority risk or unknown;
• whether the project is ready for the requested downstream work;
• links or locations for the exploration outputs.

Do not overwhelm the final response with the entire dossier.

Completion Criteria

Exploration is complete only when:

• root instructions and manifests were inspected;
• all primary applications, services, or packages were inventoried;
• at least one important runtime flow was traced end to end;
• core domain concepts were identified;
• primary data stores and external interfaces were mapped;
• development commands were verified or honestly classified;
• critical tests and quality signals were inspected;
• high-impact risks and fragile zones were identified;
• contradictory evidence was actively checked;
• unknowns were recorded rather than guessed away;
• mandatory outputs were generated;
• major conclusions include evidence and confidence;
• the dossier gives a downstream agent a clear starting point.

If a completion item cannot be satisfied, mark exploration as Partial, explain the blocker, and state which decisions are unsafe until resolved.

Handoff to Other Skills or Agents

VIBE-EXPLORE should normally run before planning or implementation skills.

Suggested chain:

1. VIBE-EXPLORE — understand and map the project.
2. Planning skill — define the change using verified project constraints.
3. VIBE-EXECUTER or implementation agent — make and validate changes.
4. Review or testing skill — independently verify results.

The downstream handoff must include:

• target modules and files;
• relevant runtime flow;
• constraints and invariants;
• commands to validate changes;
• known risks;
• unresolved blockers;
• evidence-backed confidence.

Compact Agent Instruction

When a full skill loader is unavailable, use this compact instruction:

Explore this project as an unfamiliar codebase before changing it. Work read-only unless explicitly authorized. Inspect instructions, manifests, structure, entry points, runtime flows, domain concepts, data stores, interfaces, tests, commands, deployment, security boundaries, risks, and contradictory evidence. Cite important conclusions by file and line or symbol. Label facts, inferences, contradictions, and unknowns. Trace at least one end-to-end flow. Produce PROJECT_EXPLORATION_REPORT.md, PROJECT_MAP.md, COMMANDS.md, OPEN_QUESTIONS.md, and EXPLORATION_MANIFEST.json. Do not claim commands passed unless you ran them. Finish with confidence-scored findings and an actionable handoff for the next coding agent.