multi-source-synthesis

# Multi-Source Synthesis You transform raw Layer 1 intelligence into structured synthesis documents. You merge findings from multiple independent analysis modes into corroborated, conflict-resolved behavioral descriptions that Layer 3 can write deep specs from. ## The Core Principle **Merge independently. Resolve conflicts explicitly. Cite everything. Miss nothing.** - **Merge:** Every behavioral claim from every available mode gets collected, compared, and synthesized. - **Resolve:** When modes disagree, apply the conflict resolution hierarchy. Record BOTH claims with provenance. - **Cite:** Every synthesized claim traces back to Layer 1 evidence with `<!-- cite: -->` annotations. - **Complete:** Every feature, every component, every interface, every module must appear in synthesis output. ## Layer 2 Pipeline ```dot digraph layer2_pipeline { rankdir=TB; subgraph cluster_inputs { label="Layer 1 Intelligence Sources"; style=dashed; "Source Code Analysis" [shape=folder]; "Public Documentation" [shape=folder]; "SDK / Ecosystem" [shape=folder]; "Runtime Observation" [shape=folder]; "Binary Analysis" [shape=folder]; "Community Intelligence" [shape=folder]; } subgraph cluster_phase1 { label="Phase 1 (parallel)"; style=filled; fillcolor="#e8f4e8"; "feature-discoverer" [shape=box]; "architecture-analyst" [shape=box]; "api-extractor" [shape=box]; } subgraph cluster_phase2 { label="Phase 2"; style=filled; fillcolor="#e8e8f4"; "analysis-synthesizer" [shape=box]; } subgraph cluster_phase3 { label="Phase 3"; style=filled; fillcolor="#f4e8e8"; "module-mapper" [shape=box]; } "Source Code Analysis" -> "feature-discoverer"; "Source Code Analysis" -> "architecture-analyst"; "Source Code Analysis" -> "api-extractor"; "Public Documentation" -> "feature-discoverer"; "Public Documentation" -> "architecture-analyst"; "Public Documentation" -> "api-extractor"; "SDK / Ecosystem" -> "feature-discoverer"; "SDK / Ecosystem" -> "api-extractor"; "Runtime Observation" -> "feature-discoverer"; "Runtime Observation" -> "architecture-analyst"; "Runtime Observation" -> "api-extractor"; "Binary Analysis" -> "architecture-analyst"; "Community Intelligence" -> "feature-discoverer"; "feature-discoverer" -> "analysis-synthesizer"; "architecture-analyst" -> "analysis-synthesizer"; "api-extractor" -> "analysis-synthesizer"; "Source Code Analysis" -> "analysis-synthesizer" [style=dashed, label="raw L1"]; "Public Documentation" -> "analysis-synthesizer" [style=dashed, label="raw L1"]; "Runtime Observation" -> "analysis-synthesizer" [style=dashed, label="raw L1"]; "analysis-synthesizer" -> "module-mapper"; "feature-discoverer" -> "module-mapper"; "architecture-analyst" -> "module-mapper"; "api-extractor" -> "module-mapper"; "module-mapper" -> "Layer 3 Deep Dives" [shape=doublecircle]; } ``` ### Phase Execution Rules - **Phase 1** agents run in parallel. They share no output with each other. Each reads only Layer 1 directories. - **Phase 2** runs after ALL Phase 1 agents complete. The analysis-synthesizer reads Phase 1 output AND raw Layer 1 findings. - **Phase 3** runs after Phase 2 completes. The module-mapper reads ALL Phase 1 and Phase 2 output. No phase advances until the previous phase is fully complete. ## Input Sources All Layer 2 agents consume output from Layer 1. Not all modes will be present for every analysis run. ``` Required (at least one must exist): workspace/raw/source/analysis/ Source code chunk analyses workspace/public/docs/ Documentation research output workspace/public/ecosystem/ SDK and ecosystem analysis workspace/public/community/ Community intelligence (forums, tutorials, issues) workspace/raw/runtime/ Runtime observation output workspace/raw/binary/ Binary analysis output Phase 1 output (consumed by Phase 2 and Phase 3): workspace/raw/synthesis/features/ feature-discoverer output workspace/raw/synthesis/architecture/ architecture-analyst output workspace/raw/synthesis/api/ api-extractor output Phase 2 output (consumed by Phase 3): workspace/raw/synthesis/behavioral-summaries/ analysis-synthesizer output workspace/raw/synthesis/cross-reference-report.md workspace/raw/synthesis/reimplementation-essentials.md ``` ### Availability Detection Every Layer 2 agent runs this check before starting. Record results in output metadata. ```bash [ -d "workspace/raw/source/analysis/" ] && HAS_SOURCE=true || HAS_SOURCE=false [ -d "workspace/public/docs/" ] && HAS_DOCS=true || HAS_DOCS=false [ -d "workspace/public/ecosystem/" ] && HAS_SDK=true || HAS_SDK=false [ -d "workspace/public/community/" ] && HAS_COMMUNITY=true || HAS_COMMUNITY=false [ -d "workspace/raw/runtime/" ] && HAS_RUNTIME=true || HAS_RUNTIME=false [ -d "workspace/raw/binary/" ] && HAS_BINARY=true || HAS_BINARY=false ``` At least one must be true. If zero modes contributed, halt with an error. ### Mode Coverage Summary Every synthesis output file includes this table at the top: ```markdown ## Mode Coverage Summary | Mode | Available | Items Discovered | |------|-----------|------------------| | Source Code | YES/NO | [count] | | Public Docs | YES/NO | [count] | | SDK / Ecosystem | YES/NO | [count] | | Community | YES/NO | [count] | | Runtime Observation | YES/NO | [count] | | Binary Analysis | YES/NO | [count] | ``` ### Single-Mode Pass-Through When only one intelligence source is available, cross-referencing is skipped. All findings retain their single-mode confidence (`inferred`). Structural output is still produced. Corroboration tables show one source column. Coverage gaps note the absent modes but do not flag single-source claims from the only available mode as deficiencies. --- ## 1. Feature Discovery Methodology **Agent:** feature-discoverer | **Phase:** 1 (parallel) | **Output:** `workspace/raw/synthesis/features/` ### Goal Exhaustive feature inventory. Find every feature the target exposes, including those nobody documents. ### What Counts as a Feature | Category | Examples | |----------|----------| | CLI flags | `--help`, `--verbose`, `--config`, hidden flags | | CLI subcommands | `init`, `config`, `serve` | | Interactive commands | `:help`, `/quit`, `:exit` | | Keyboard shortcuts | `Ctrl+C`, `Ctrl+D`, `Up Arrow`, `Escape` | | Environment variables | `API_KEY`, `DEBUG`, `LOG_LEVEL` | | Config file keys | `log_level`, `autoUpdate`, `upstreams` | | API endpoints | `POST /v1/chat`, `GET /health` | | File formats | `.json`, `.yaml`, `.toml` read or written | | UI elements | Buttons, menus, panels, prompts, spinners | | Plugin/extension points | Hook APIs, plugin loaders, extension registries | ### Discovery Patterns by Mode Each intelligence source reveals features through different patterns: **Source code:** Grep for flag definitions (`--[a-z][-a-z0-9]*`), `process.env.` accesses, config key reads, command handler registrations, event listener setups, key binding registrations. **Public documentation:** Extract feature descriptions, capability lists, configuration references, API endpoint listings, changelog entries for new features. **Runtime observation:** Observed CLI flags from `--help` output, environment variable effects, API endpoints hit during exploration, interactive command responses, UI element interactions. **SDK / Ecosystem:** API operations and method signatures, request builder parameters, configuration options exposed through client libraries. **Community intelligence:** Tutorials reveal feature usage patterns, Stack Overflow answers expose hidden features, blog posts describe undocumented capabilities. **Binary analysis:** String extraction reveals feature names, flag definitions, config keys embedded in compiled artifacts. ### Feature Entry Format Each discovered feature records: ```markdown | Feature | Category | Description | Discovery Sources | Confidence | |---------|----------|-------------|-------------------|------------| | --workers | CLI flag | Set worker pool size | source-code, official-docs, runtime | confirmed | | --debug | CLI flag | Enable debug logging | source-code | inferred | ``` ### Cross-Mode Corroboration - Feature found in 1 mode: `inferred` confidence - Feature found in 2 modes: `confirmed` confidence (if independent modes) - Feature found in 3+ modes: `confirmed` with strong corroboration - Feature in docs but NOT in source code: flag as discrepancy (docs may describe planned/removed feature) - Feature in source code but NOT in docs: flag as undocumented (hidden/debug/experimental) ### Output Files ``` workspace/raw/synthesis/features/ feature-inventory.md # Complete flat inventory of all features features-by-category.md # Grouped: CLI, config, API, UI, etc. features-by-priority.md # Grouped by implementation priority features-cli.md # CLI flags, subcommands, arguments features-commands.md # Interactive/runtime commands features-shortcuts.md # Keyboard shortcuts features-environment.md # Environment variables features-config.md # Config file keys ``` Each file ends with a Source Corroboration table showing per-feature mode coverage. --- ## 2. Architecture Reverse Engineering Methodology **Agent:** architecture-analyst | **Phase:** 1 (parallel) | **Output:** `workspace/raw/synthesis/architecture/` ### Goal Identify subsystems and their relationships from all available intelligence. Produce a structural map of the target. ### Architecture Document Structure The architecture analysis produces four perspectives: | Perspective | Content | Key Questions | |-------------|---------|---------------| | **System Context** | External interfaces, actors, integrations | What does the system talk to? | | **Component Architecture** | Subsystems, modules, internal boundaries | What are the major pieces? | | **Data Architecture** | Data stores, formats, flow patterns | How does data move through the system? | | **Integration Architecture** | External dependencies, protocols, API contracts | What third-party systems does it depend on? | ### Component Identification by Mode **From source code:** Import graphs, module boundary markers (webpack comments, esbuild markers, IIFE boundaries), class/function catalogs, string-based component discovery (Manager/Service/Handler patterns). **From runtime observation:** Process/thread model, port bindings, service startup sequences, IPC channels, file handles opened, network connections established. **From documentation:** Architecture diagrams, component descriptions, system overview sections, deployment documentation. **From SDK / Ecosystem:** API groupings reveal component boundaries, client method namespaces map to server-side components. **From binary analysis:** Binary structure reveals module organization, symbol tables expose component boundaries. ### Cross-Referencing Components Across Modes When multiple modes identify the same component, record the corroboration: ```markdown ### Component: API Server | Mode | Evidence | |------|----------| | Source Code | Request handling in chunks 003-005, routing logic, middleware chain | | Public Docs | API reference describes REST endpoints and authentication | | Runtime | HTTP server observed listening on port 3000 | | SDK | Client library has `ClientAdapter` class with matching method names | **Confidence:** confirmed (4 independent sources) ``` When modes identify different components, both are included. When mode perspectives conflict (documented architecture differs from source code organization), record the discrepancy explicitly. ### Output Files ``` workspace/raw/synthesis/architecture/ architecture.md # Full architecture document (all 4 perspectives) components.md # Component catalog with relationships component-map.md # Visual/structural component map data-flows.md # Data flow mapping (I/O boundaries, internal flow) dependencies.md # External dependency catalog entry-points.md # All ways to invoke the system architecture-sources.md # Per-component mode evidence table notes/ # Raw findings captured during analysis ``` --- ## 3. API Surface Extraction Methodology **Agent:** api-extractor | **Phase:** 1 (parallel) | **Output:** `workspace/raw/synthesis/api/` ### Goal Extract every public interface the target exposes. If it can be called, configured, or observed from outside the system, it belongs here. ### API Types to Extract | API Type | What to Capture | |----------|----------------| | **CLI Interface** | Flags, subcommands, arguments, exit codes, stdin/stdout/stderr behavior | | **HTTP / REST API** | Endpoints, methods, request/response schemas, auth, rate limiting, error codes | | **WebSocket / Streaming** | Connection lifecycle, message formats, event types | | **Configuration API** | Config files, their locations, keys, value types, defaults | | **Environment Variable API** | Variable names, purposes, defaults, required vs optional | | **Plugin / Extension API** | Hook points, plugin lifecycle, extension interfaces | | **Library / Programmatic API** | Exported functions, classes, constants, type signatures | | **Event API** | Events emitted, events consumed, hook callbacks | | **File Format API** | Files read/written, their formats, schema |