- name
- parallel-explore
- description
- Parallel exploration of codebase questions by decomposing into independent tracks. Use when exploring architecture, understanding systems, or investigating complex questions that benefit from multiple perspectives.
<exploration> <philosophy> exploration := decompose(question) → parallel(tracks) → aggregate(findings) track := independent ∧ parallelizable ∧ logical-unit agent := explorer(track) → findings(structured) synthesis := merge(findings) → coherent(answer) </philosophy>
<decomposition> analyze :: Question → [Track] analyze question = do dimensions ← identify (orthogonal (aspects question)) granularity ← ensure (|dimensions| >= 3 ∧ |dimensions| <= 6) tracks ← map toTrack dimensions verify (independent tracks) pure tracks
-- each track explores one dimension without overlap -- tracks are logical units of investigation -- minimum 3 tracks to ensure sufficient coverage </decomposition>
<track> data Track = Track { name :: String -- short identifier , focus :: Scope -- what to investigate , approach :: Strategy -- how to investigate , gates :: [Gate] -- verification checkpoints , deliverable :: Artifact -- what to return }
data Gate = Gate { checkpoint :: Condition -- what must be true , verification :: Command -- how to verify }
-- each track subdivides into gated steps -- step N must pass gate before step N+1 </track>
<when-to-use> trigger :: Question → Bool trigger question | complex (architecture question) = True | multiple (dimensions question) = True | benefits (parallelPerspectives) = True | investigating (multiCauseBug) = True | researching (crossCuttingPatterns) = True | otherwise = False </when-to-use>
<phases> <phase name="decomposition"> decompose :: Question → Effect [Track] decompose question = do aspects ← identify (dimensions question) tracks ← traverse toTrack aspects verify (all independent tracks) pure tracks </phase>
<phase name="dispatch"> dispatch :: [Track] → Effect [Agent] dispatch tracks = parallel $ fmap spawnExplorer tracks
spawnExplorer :: Track → Effect Agent spawnExplorer track = spawn Explore (prompt track) </phase>
<phase name="aggregate"> aggregate :: [TrackFindings] → Synthesis aggregate findings = do common ← intersect (conclusions findings) divergent ← difference (conclusions findings) gaps ← union (uncertainties findings) confidence ← assess divergent pure $ Synthesis { common, divergent, gaps, confidence } </phase> </phases>
<module-specialists> -- ADDITION to parallel tracks, not replacement -- When complex modules detected → spawn module specialists in parallel with tracks -- Targets BOTH Effect library modules AND internal codebase modules
detect :: Code → [Module] detect code = filter isComplex (modulesUsed code)
isComplex :: Module → Bool isComplex m = isEffectModule m ∨ isCodebaseModule m
isEffectModule :: Module → Bool isEffectModule m = m ∈ { Stream, Layer, Fiber, Scope, Schema, Effect.gen, Match }
isCodebaseModule :: Module → Bool isCodebaseModule m = m ∈ /modules -- internal modules with ai-context.md
data ModuleSource = EffectLibrary | CodebaseInternal
moduleSource :: Module → ModuleSource moduleSource m | isEffectModule m = EffectLibrary | isCodebaseModule m = CodebaseInternal
spawn :: Module → Effect Specialist spawn m = do context ← case moduleSource m of EffectLibrary → /module m -- external Effect documentation CodebaseInternal → /module path -- internal ai-context.md scope ← extractUsage m code -- ONLY how m is used pure $ Specialist { context := context -- module documentation only , scope := scope -- usage patterns in code , goal := efficiency -- missed conveniences, anti-patterns , constraint := reviewOnly -- no implementation, just review }
<specialist-prompt> You are a [MODULE] specialist.
Your ONLY context: the /module [MODULE] documentation Your ONLY scope: how [MODULE] is used in the provided code Your ONLY goal: identify efficiency issues
Review for:
- Missed conveniences (simpler APIs available)
- Anti-patterns (common misuse)
- Idiomatic alternatives (more Effect-like approaches)
Output:
- Specific file:line citations
- What could be improved
- How to improve it (idiomatic pattern)
Do NOT:
- Implement changes
- Review anything outside [MODULE] usage
- Consider broader architecture
</specialist-prompt>
<composition> explore :: Question → Code → Effect Synthesis explore question code = do -- Regular parallel tracks (existing behavior) tracks ← decompose question trackAgents ← dispatch tracks
-- ADDITION: module specialists (orthogonal overlay) modules ← detect code specialists ← parallel (spawn <$> modules)
-- Aggregate both trackFindings ← await trackAgents specialistFindings ← await specialists
aggregate (trackFindings ++ specialistFindings) </composition> </module-specialists>
<agent-prompt> <execution> execute :: Track → Effect Findings execute track = do context ← gatherContext track gate₁ ← verify (understood context) findings ← explore context track gate₂ ← verify (evidence findings) summary ← synthesize findings gate₃ ← verify (complete summary) pure summary </execution>
<gates> gate :: Checkpoint → Effect () gate = \case Understood ctx → can describe files/patterns found Evidence fnd → every claim has file:line citation Complete sum → summary answers track question </gates>
<output> data TrackFindings = TrackFindings { track :: String , findings :: [(Finding, Citation)] , evidence :: [(FilePath, LineNumber, Description)] , conclusions :: Text , gaps :: [Uncertainty] } </output> </agent-prompt>
<synthesis> <output> data Synthesis = Synthesis { unified :: Text , nuances :: [Divergence] , openQuestions :: [Gap] , confidence :: Confidence }
data Confidence = High | Moderate | Low </output> </synthesis>
<recursive> deepen :: Track → Effect Synthesis deepen track = do subtracks ← decompose (question track) agents ← dispatch subtracks findings ← await agents aggregate findings
-- apply same decomposition recursively for deeper exploration </recursive> </exploration>