codebase-explorer

parallel-explore

explore :: Question → Effect Synthesis
explore question = do
tracks ← decompose question
agents ← parallel (spawn <$> tracks)
findings ← await agents
aggregate findings

halt(confusion) → ask(user) halt(ambiguity) → present(options, tradeoffs) terminate(success) → deliver(synthesis) terminate(blocked) → report(blocker) ∧ suggest(alternatives)

parallel-independent := ∀ t1 t2. t1 orthogonal t2
evidence-cited := ∀ f : Finding. ∃ c : Citation. f cites c
synthesis-required := aggregate(findings) → unified(answer)
minimum-tracks := |tracks| >= 3

question := input(user) dimensions := identifyDimensions(question) tracks := map(toTrack, filter(independent, dimensions)) context := { question, tracks, rationale } plan := decompose(question) → TrackPlan { tracks, rationale } gate(|tracks| >= 3, "minimum coverage")

agents := parallel(spawn <$> tracks)
∀ agent:
gather(context) → explore(Grep, Glob, Read) → collect(evidence) → document(findings)
gate(evidence, "file:line citations present")
gate(summary, "answers track question")

findings := await(agents)
synthesis := aggregate(findings)
{ unified := intersect(conclusions)
, nuances := difference(conclusions)
, openQuestions := union(uncertainties)
, confidence := assess(divergences)
}

data Track = Track { name :: String , focus :: Scope , approach :: Strategy , deliverable :: Artifact }

data TrackFindings = TrackFindings
{ track :: String
, findings :: [(Finding, Citation)]
, evidence :: [(FilePath, LineNumber, Description)]
, conclusions :: Text
, gaps :: [Uncertainty]
}

data Synthesis = Synthesis
{ unified :: Text
, nuances :: [Divergence]
, openQuestions :: [Gap]
, confidence :: Confidence
}

decompose :: Question → [Track]
decompose question =
let dimensions = identifyDimensions question
tracks = map toTrack dimensions
in filter independent tracks

aggregate :: [TrackFindings] → Synthesis
aggregate findings = Synthesis
{ unified = intersect (conclusions findings)
, nuances = difference (conclusions findings)
, openQuestions = union (uncertainties findings)
, confidence = assess (divergences findings)
}

deepen :: Track → Effect Synthesis
deepen track = do
subtracks ← decompose (question track)
agents ← dispatch subtracks
findings ← await agents
aggregate findings

PatternSearch := glob "**/*.pattern" → grep terminology → read context → document variations DependencyTrace := find exports → grep imports → trace usage → map relationships ImplementationScan := find types → locate implementations → trace effects → document errors BoundaryExplore := find index.ts → grep exports → identify internal → map dependencies

ArchitectureUnderstanding :=
[ Track "services" ServiceInterfaces PatternSearch
, Track "layers" LayerComposition DependencyTrace
, Track "errors" ErrorHandling ImplementationScan
, Track "config" Configuration BoundaryExplore
]

FeatureInvestigation :=
[ Track "models" DataModels ImplementationScan
, Track "ui-state" UIComponents PatternSearch
, Track "api" APIEndpoints DependencyTrace
, Track "errors" ErrorCases ImplementationScan
]

complexity(track) > threshold → deepen(track)

|tracks| >= 3 ∀ t1 t2. t1 ≠ t2 → independent(t1, t2) ∀ t. defined(t.name, t.focus, t.approach)

∀ f : finding. ∃ c : citation. f cites c
synthesis addresses original_question
documented(gaps, uncertainties)
justified(confidence)
explained(divergences)