Holmes LabAgentic Software Engineering Architect

Find change impact and missing files

Determine scope using graph candidates, changed files and actual tests together.

Guide verification basis: Holmes-Kit 0.40.0 · 2026-11-05 · Installation target: latest at execution time

Prerequisites, evidence and installation tradeoffs

Before you start

  • Your own workspace and connected MCP session after the basics. Define HOLMES_CLI or PowerShell HolmesCli from the installation step in this terminal and verify its file and version.
  • A change request and actual changedFiles or Git comparison basis

Explain which files need edits and verification, along with analysis limits.

Documented for 0.40.0 · release contracts reviewed 2026-11-04. Native evidence is the historical 0.39.0 run of 2026-11-01. Read-only binding matched for Codex and Claude in an independent macOS workspace. Claude hook events were observed but routing is unverified; Codex hooks were not observed. Native revalidation on 0.40.0 and RED/GREEN acceptance of a small governed change remain incomplete. Windows/Linux instructions have no native acceptance run.

1. Separate user folder
Keeps project dependencies and global npm installation unchanged; separate versioned folder. Manage its path and updates separately; retain the folder while workspaces use it.
2. Project local
Project/team versioning through a lockfile; recommended for the practice project. Changes package.json and lockfile; may introduce npm metadata to a non-Node project.
3. Global npm
Convenient shared installation across projects. Check write permissions and update impact on all projects sharing this installation.

Package location and client settings are separate. Even project-local Codex wiring may change user-level settings.

Step 1 / 4

Fix the comparison basis

Choose working-tree changes or a specific commit comparison.

Terminal in the confirmed projectShared

Terminal in your workspace

git diff --name-only
git diff --cached --name-only
git ls-files --others --exclude-standard
git diff --stat
git diff --cached --stat
Paste into your AI CLIShared

Ask your agent

Union and deduplicate the unstaged, staged and untracked file lists into changedFiles, inspecting new-file contents too. For a commit comparison, name the exact base and head and derive paths from that comparison. Run maintenance_analyze for this request with persist:true and retain comparison basis and evidenceDigest.

Expected result — inspect your actual output

  • The analysis points to the current file set and revision.
A manual learning note, not automatic verification of your workspace.
If the result differs

Analysis is stale or the architecture axis is not assessed.

Reanalyze with current changedFiles; do not interpret not assessed as no impact.

What the agent does / terms

Read actual changed files and connect request, paths and revision basis to the analysis.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 2 / 4

Read rankings as hypotheses

Separate direct edit candidates from candidates needing investigation.

Paste into your AI CLIShared

Ask your agent

Check direct evidence for each maintenance_analyze candidate. Do not use confidence as correctness probability; summarize relevant tests, unresolved calls and constraints together.

Expected result — inspect your actual output

  • Required edits are justified by actual code relationships.
A manual learning note, not automatic verification of your workspace.
If the result differs

A top candidate only shares a name and has no relevant call relationship.

Inspect code to discard or downgrade the candidate while separately recording possible omissions.

What the agent does / terms

Read rankedImpact, relevantTests, constraints and unknowns; inspect call, contract and co-change evidence.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 3 / 4

Find incomplete changes

Review whether the reported paths are actually necessary.

Paste into your AI CLIShared

Ask your agent

Inspect missingNewFiles and removedNameUsers for changedFiles. Verify actual import resolution and users of removed names, and label out-of-coverage paths such as aliases and dynamic calls.

Expected result — inspect your actual output

  • Missing targets and remaining users are reproducible; inferences are separated.
A manual learning note, not automatic verification of your workspace.
If the result differs

The result is empty but a runtime import fails.

An empty result does not guarantee completeness. Check aliases and dynamic paths with the project resolver and actual tests.

What the agent does / terms

Inspect missingNewFiles and removedNameUsers and report relative-import, language and working-tree limits.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Step 4 / 4

Reconcile specification and test scope

Decide whether the new impact is necessary for the goal.

Paste into your AI CLIShared

Ask your agent

Check whether additional impact exceeds approved scope. If needed, review specifications first, then compare relevant regression tests and the actual diff to report gaps.

Expected result — inspect your actual output

  • The final diff, specifications and test scope agree.
A manual learning note, not automatic verification of your workspace.
If the result differs

Relevant tests expose a new failure.

Record the real dependency path, review scope and fix it; do not exclude a failing test to make scope appear consistent.

What the agent does / terms

Complete required specification review, run relevant tests and compare predicted impact with actual results.

MCP
The connection through which your AI calls Holmes tools.
REQ → H-SPEC → A-SPEC → T-SPEC
Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
Hook / binding
A pre/post execution check / matching this session to the intended project and server.

Recorded Holmes Lab change

A-SPEC-101.21 restored three hidden primary links on home—Technical journey, Work and Practice—removed graph fallback JSON links and expanded Practice content. RED, regression and build records in docs/evidence/engineering-perspective are historical evidence. Running these instructions in your project is a reproduction, not that historical execution.

Related case ↗

Continue with your project

Use Adoption for existing code without specs, or Requirements when specifications already exist. Other workflows require their stated prerequisites.