Skip to content

richfrem/agent-plugins-skills / plugins/agent-exploration-cycle/.apm/skills/running-exploration-cycle

running-exploration-cycle

Verified

Runs the business exploration cycle end to end: starts or resumes a session (intake interview, session brief), enforces the Discovery Plan HARD-GATE, routes the four phases (Discovery Plan, Visual Blueprinting, Prototype, Handoff) to the sibling skills and keeps session state. Use when the user says "let's explore this idea", "I have an idea I want to explore", "help me plan this out", "start discovery", "resume my exploration", "where did we leave off", or starts any conversation about a need, problem or idea before building. Not for hardening an existing prototype (use reengineering-vibe-code) or for engineering build work.

FileKindSize
SKILL.mdskill md4.6 KB
assets/exploration-dashboard.mdmarkdown1.8 KB
evals/evals.jsonconfig6.0 KB
references/acceptance-criteria.mdmarkdown2.2 KB
references/architecture.mdmarkdown6.3 KB
references/design-rationale.mdmarkdown6.3 KB
references/discovery-planning-agent.mdmarkdown4.7 KB
references/discovery-planning-tracks.mdmarkdown5.9 KB
references/discovery-planning.mdmarkdown2.4 KB
references/dispatch-strategies.mdmarkdown5.7 KB
references/domain-patterns-exploration-session.mdmarkdown3.3 KB
references/domain-patterns.mdmarkdown1.7 KB
references/environment-check.mdmarkdown1.7 KB
references/exploration-cycle-orchestrator-agent.mdmarkdown16.7 KB
references/exploration-optimizer.mdmarkdown8.9 KB
references/exploration-orchestrator-guide.mdmarkdown3.7 KB
references/exploration-session-brief.mdmarkdown2.1 KB
references/exploration-workflow.mdmarkdown2.4 KB
references/hard-gate-enforcement.mdmarkdown3.3 KB
references/high-level-process.mmdother885 B
references/intake-agent.mdmarkdown12.0 KB
references/orchestrator-loop.mmdother1.3 KB
references/post-run-survey.mdmarkdown1.7 KB
references/problem-framing-agent.mdmarkdown2.7 KB
references/process-definition.mdmarkdown3.7 KB
references/process-overview.mmdother3.7 KB
references/session-setup.mmdother1.3 KB
references/state-and-gates.mmdother1.0 KB
references/using-exploration-cycle.mdmarkdown2.3 KB
requirements-dev.inother69 B
requirements.inother60 B
scripts/check_gaps.pyscript2.5 KB
scripts/dispatch.pyexecutablescript23.6 KB
scripts/exploration_session.pyexecutablescript15.9 KB
scripts/sandbox_runner.pyscript8.7 KB
scripts/smoke_test.pyscript5.1 KB
scripts/state_engine.pyscript21.9 KB
scripts/test_dispatch_authorization_gate.pyscript4.0 KB
scripts/test_dispatch_security.pyscript10.0 KB
scripts/test_exploration_integration.pyscript14.7 KB
scripts/test_integration.pyscript4.4 KB
scripts/test_path_traversal.pyscript1.8 KB
scripts/test_phase_premium_counter.pyscript2.0 KB
scripts/test_sandbox_runner.pyscript5.6 KB
scripts/test_session_start_hook.pyscript2.4 KB
scripts/test_state_engine.pyscript13.5 KB
scripts/test_validate_phase_gate.pyscript12.7 KB
scripts/validate_phase_gate.pyexecutablescript8.7 KB

references/domain-patterns-exploration-session.md

View on GitHub
# Domain Patterns: Exploration Session Failures

Failures at the session orchestration level: classification, gate enforcement, state management. Use when the improvement-loop target is `running-exploration-cycle`. Reviewed during the consolidation: each pattern notes what changed.

## Known Patterns

### Pattern 1: Session type misclassification leads to the wrong phase set

**Failure type:** the expert describes a process problem but is classified as Greenfield, which enables Phase 3 (prototype) when the real deliverable is a process change recommendation.

**Root cause:** routing on keywords ("workflow", "approval") that appear in both software and process-change contexts. The Intervention Check (Greenfield track question 4 in [discovery-planning-tracks.md](discovery-planning-tracks.md)) catches this only if it fires.

**Escape:**
- Make Phase 0 classification ([intake-agent.md](intake-agent.md)) check the explicit signal "existing manual process" versus "no process exists yet"; only the latter is Greenfield.
- Add a negative example to the `running-exploration-cycle` evals: a process-change scenario that looks Greenfield but routes to Analysis/Docs.
- Ensure the Intervention Check always fires, even when the routing seems confident.

**Confirmed improvements:** 2+ (recorded by the retired optimizer loop). *Review: the original named a "routing guide" and `discovery-planning/SKILL.md`; those now live in intake and the discovery-planning reference.*

### Pattern 2: HARD-GATE bypass via "quick question" framing

**Failure type:** the expert opens with "just a quick question" and the agent starts capturing requirements without a Discovery Plan.

**Root cause:** the gate was prose. A low-stakes trigger reads as a clarification, not a session start.

**Escape:**
- Add "quick question about" and "wondering if" as should-route-to-gate cases in the `running-exploration-cycle` evals and keep the skill's HARD-GATE constraint first.
- Before any capture begins, verify that an approved Discovery Plan exists or that the session is in Phase 0.

**Confirmed improvements:** 3+. *Review: partly enforced in code since the consolidation. `validate_phase_gate.py 1` now rejects a plan without `PLAN_STATUS: APPROVED` or `## SME Approval`, so a DRAFT cannot pass; the prose check at the start of capture is still advisory (a pre-write hook was planned and never built).*

### Pattern 3: Premature handoff, Phase 4 before Phase 3 artifacts exist

**Failure type:** the conductor routes to Phase 4 before prototype artifacts are confirmed, producing a handoff with an empty "Prototype Notes" section.

**Root cause:** the read-state block (Block 2) checks outcome files for completed phases, but the Phase 3 outcome is `exploration/prototype/index.html`, and agents sometimes write only `README.md` and mark Phase 3 complete.

**Escape:**
- Before marking Phase 3 complete, verify that both `index.html` and `README.md` exist under `exploration/prototype/` for Greenfield sessions.
- For Analysis/Docs and legacy-brownfield sessions (Phase 3 skipped), skip this check; the `[~]` marker is the authority.

**Confirmed improvements:** 2+. *Review: implemented. `validate_phase_gate.py 3` requires `README.md`, `captures/prototype-notes.md`, and, for Greenfield sessions, `index.html`.*

## Novel candidates (awaiting a second confirmation)

None recorded.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall