aid-discover

Brownfield Project Discovery

Analyze an existing project repository — all code, configuration, and documentation — and produce a structured .aid/knowledge/ directory by orchestrating 5 specialized discovery subagents. Includes a built-in quality gate that reviews, grades, and fixes KB documents.

State machine — each /aid-discover invocation drives the state machine until it hits a natural pause point per .aid/runtime/templates/state-machine-chaining.md. Mechanical states and inline-question states auto-chain; only PAUSE-FOR-USER-ACTION, PAUSE-FOR-USER-DECISION, and HALT stop the run.

⛔ PRIME DIRECTIVE: NO ASSUMPTIONS — DEFER TO THE USER

This rule governs every state, every sub-agent, and the orchestrator itself. It overrides convenience, speed, and confidence.

Discovery's job is to report what the project actually is, never what an agent guesses it is. So whenever ANYTHING is unclear, ambiguous, contradictory, or a judgment call — an undefinable term, a discrepancy between two sources, an uncertain classification, which of two things is authoritative, in-or-out-of-scope, how to resolve a conflict — DO NOT resolve it by assumption. Record a question and DEFER the decision to the user.

• A LIKELY / UNCERTAIN / probably / "I'll assume" answer written into the KB is a FAILURE, not a finding. Turn it into a Q&A entry.
• Never silently reconcile a contradiction — record both sides and ask which is right.
• State a fact only when you can ground it from the artifacts with certainty (cite the source). Otherwise, ASK.

The deferral machinery is already built in — use it: the Step 0cx (domain), 0d (doc-set), 0f (path), and Step 5c (term-exclusion) gates are PAUSE-FOR-USER-DECISION points; sub-agents write open questions to .aid/knowledge/.scout-questions.tmp; Step 6b consolidates them into STATE.md ## Q&A (Pending); and the Q-AND-A state resolves them with the user before approval. Every disambiguation flows through this path — none is decided silently.