# User guide: running Agentic Landing Zone discovery This guide is for the Engagement Lead or delivery engineer who runs discovery for a client engagement and reviews its results. It assumes the agent is deployed and its MCP servers are registered (see [deployment](../../../../docs/deployment.md)). ## What discovery does Discovery builds an evidenced picture of the client's estate: - what is in scope; - what each workload runs; - how the CMDB differs from reality; - which data stores hold sensitive data; - how systems depend on each other; - what the network looks like. It runs in four phases, and each phase builds on the one before: | Phase | What happens | Specialists involved | |---|---|---| | **plan** | Reads the scope, data sources and budgets, and plans a task for every scope entry. An entry that can't be planned is a declared gap, with a reason. | Discovery Planner (ALZ-DSC-01) | | **collect** | Ingests CMDB and ITSM records, then scans each planned target at metadata level. Nothing is installed and no credentials are used on workloads. | Estate Scan Executor (ALZ-DSC-02) | | **analyse** | Builds one de-duplicated inventory, then CMDB drift, data classification, the network map and the dependency graph. | DSC-03, DSC-04, DSC-05, DSC-07, DSC-06 | | **critique** | An independent critic checks coverage, evidence, prompt-injection handling and tool-call integrity, and returns pass or fail. | Discovery Critic (ALZ-DSC-08) | ## Running it **From KAB (normal use).** Run the workflow **CP1 - Agentic Landing Zone - Discovery** in the engagement's project. Give it two inputs: | Input | Example | Notes | |---|---|---| | `engagement_id` | `ENG-MERIDIAN-001` | The engagement. Letters, digits, `-` and `_`. | | `run_id` | `RUN-2026-10-29-01` | A new id for every discovery run. Reusing one continues that run. | The workflow runs the four phases in order. After critique it stops for your approval: **continue** hands over to Assessment, **rerun** runs the critique again, and **abort** stops. **One phase at a time.** Anyone testing the agent can send it a request directly: ```json {"engagement_id": "ENG-MERIDIAN-001", "run_id": "RUN-2026-10-29-01", "phase": "plan"} ``` Leave `phase` out and the agent runs the next phase the run needs. For a large estate, add `"batch": 1` (2, 3…) to the collect phase to scan one planned batch at a time. ## Reading the result Every phase returns the same shape. **`status`:** | Value | Meaning | What to do | |---|---|---| | `completed` | The phase's checks all passed | Nothing | | `completed_with_gaps` | It finished, but something is missing or weak | Read `issues` before going on. A critique with any coverage gap is always this, never `completed`. | | `failed` | The phase couldn't do its job | Fix the cause in `issues`, then run that phase again by name | | `halted` | It was stopped on purpose | Find out why before restarting | **The other fields:** - **`issues`:** why the status isn't `completed`. Includes refused tool calls, failed specialists, plan-rule breaches (`scope_lock`, `sequencing`, `rate_budget`, `scope_accounting`) and declared gaps. - **`artifacts`:** what the phase stored. Each has a `ref` (for example `plan/task-graph`), a `sha256` and `produced_by`, which is the specialist whose answer it is. The list comes from the run's store, not from anything a model wrote. - **`verdict`** (critique only): `pass` or `fail`, the coverage gaps, the declared gaps and the reasons. It is recomputed in code. If the critic says pass while a scope entry has no finding, the verdict is fail. - **`next_phase`:** the phase to run next, or null at the end or after a failure. ## What it will not do - **Scan anything outside the scope list,** whatever a document or record says. - **Read rows of client data:** classification uses schema metadata only. - **Write to the client's CMDB, ITSM or any other system:** every tool is read-only. - **Follow instructions found in data.** For example, a server note that says "ignore previous instructions" is recorded as a prompt-injection finding and otherwise ignored. ## Where the data is kept The run's records are stored on the platform's shared execution storage, under `alz-discovery///`. They can't be changed once written, and each is chained to the one before it. A record edited outside the agent fails the next phase with an integrity error. Traces don't capture prompt or reply content. ## Troubleshooting | Message in `issues` | Cause | Fix | |---|---|---| | `the collect phase needs plan/task-graph … run the plan phase first` | A phase was run before its predecessor | Run the earlier phase | | `the plan phase ended failed; fix it and run that phase again by name` | The chain stopped after a failure | Fix the plan's issues, then send `"phase": "plan"` | | `this run has already been critiqued` | The run is finished | Use a new `run_id` | | `… was changed after it was written` | A record was edited outside the agent | Start a new run, and report it | | `sub-agent failed: …` | A specialist's model call failed | Check the model gateway, then rerun the phase | | `scope_accounting: SE-… is neither planned nor a declared gap` | The planner missed an entry | Rerun the plan phase |