ark-explore

# /ark-explore — Recon the real project (map only)

**When:** you need a map, or leftover design work remains after imports look green.
**Not when:** the user wants edits applied (`/ark-autopilot`) or session 0 (`/ark-adopt`).

## Steps

1. Read `arkgate-check --doctor`.
2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.

## Checklist

- Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
- Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
- Hook green is not tree green (scripted edits bypass PreToolUse).

## Autonomy contract

Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is
incomplete. **Do not write** config or product code (that is `/ark-adopt` / `/ark-autopilot`).
**CLI budget:** one doctor / coverage; then open ≥12 files across ≥4 dirs; then the map.

**Still never:** weaken the config; invent `mechanical-safe` kinds; claim healthy because
plan A is empty while leftover design work remains.

Use when you need a decision-grade map or the **Primary post-green door**; hand off to
`/ark-autopilot` to apply. Day-to-day place + gate work does not require this skill.

You are a **staff engineer doing architecture reconnaissance** on *this* repository.
Ark’s CLI is a **sensor** (coverage, doctor, plan). **You** open source, entry points,
install hooks, examples/starters, and coupling evidence. Output is **decision-grade**:
ranked residual that changes the next command — **not** a celebration of ENFORCE and
**not** a paraphrase of README/ROADMAP.

## Improvement compass (process preflight)

When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
0–10 scores or Excellent/Good ranks.

**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.

**Anti false-done:** empty plan A + leftover design work → **Incomplete? yes**. Green imports alone
are not “architecture finished.”

**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
new files; place before write (`/ark-place` / prepare-write).

**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.

**Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.

## Deep modules (process)

- Prefer **deep modules**: small **interface**, complexity hidden behind it (not a depth score).
- When proposing a port/adapter or Shape pilot, **name the seam** (callers stay stable; behavior swaps behind it). One adapter → seam still hypothetical; two real adapters → seam justified.
- Apply the **deletion test** before extracting “just for tests”: if deleting the module makes complexity *vanish*, it was pass-through; if complexity *reappears* across callers, it earned its keep.
- Prefer verification **at the public interface** of the seam (locality/leverage), not private pass-through layers.
- When doctor surfaces **hot paths** or **deepening candidates**, treat them as advisory residual only — never as a gate fail; bias dual-plan B pilots toward recent churn when listed.

## Domain glossary (process)

If the consumer tree has a **domain glossary**, prefer its terms for layer/slice folders, pilot names, and next-action prose:

| Common root names (detect, do not require) |
|--------------------------------------------|
| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |

- Call out **glossary vs code** conflicts when names disagree with lived folders.
- **Missing glossary is normal** — do not warn-spam or invent a glossary file.
- Glossary content never enforces; the gate remains `ark.config.json` + scan.

## When / not when

| Use `/ark-explore` when… | Do **not** use it when… |
|--------------------------|-------------------------|
| Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` |
| **Primary post-green door:** messy / leftover design work / “clarify for AI” | Skill-shopping coverage or think for the same leftover work |
| Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
| Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
| Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |

**Post-green single path:** when doctor `postGreenPath` / ENFORCE · leftover design work is active, **this skill
(shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot`
applies one B pilot. Do not send the user to coverage or think as equal first choices.

### Status lights (rank residual; not settings)

| Light | Explore role |
|-------|----------------|
| **Suggest** | Point at `ark start` → doctor; map only if user insists on recon before setup |
| **Adapt** | Map false-green / ungoverned / concentrated edge; hand off adopt/contract before Shape vanity |
| **Enforce** | Confirm edges; if residual smells/patterns appear, auto-upgrade to dual-plan seed / shape-focus |
| **Enforce · leftover design work** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |

`/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
**You** are the full recon + pattern-planning