# Multi Service Local Environment Doctor

> Use when diagnosing a multi-service local game environment with port conflicts, process listeners, configured ports, service names, startup dependencies, and cross-project isolation concerns.

- Skill: `hoatv2211/multi-service-local-environment-doctor` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hoatv2211/multi-service-local-environment-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoatv2211/multi-service-local-environment-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: hoatv2211 (https://skillmd.com/u/hoatv2211)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoatv2211/multi-service-local-environment-doctor

---

# Multi-Service Local Environment Doctor

## Overview
Build a read-only topology of services, processes, ports, and configuration, then identify collisions without starting or stopping anything.

## When to use
Use for local server startup failures, port 27000 conflicts, MySQL 3306/3307 isolation, Redis or web listener issues, config drift, or multiple game stacks on one workstation.

## When NOT to use
Do not use to kill processes, start services, edit configs, import databases, or claim a runtime is healthy from static config alone.

## Required inputs and context discovery
Collect service names, executable or script paths, expected and configured hosts/ports, dependency order, process snapshot, listener snapshot, config files, project ownership, and forbidden service-control actions.

## Safety and risk level
Read-only only. Process and port inspection is allowed; start, stop, kill, firewall, registry, database, and config changes require explicit approval and another workflow.

## Workflow
1. Inventory declared services and configuration sources.
   Completion criterion: each service has an owner, config path, expected host, and expected port.
2. Capture active processes and listeners without controlling them.
   Completion criterion: observed listeners are a timestamped Snapshot.
3. Compare expected, configured, and observed ports and dependencies.
   Completion criterion: collisions, missing listeners, and mismatches are separated.
4. Identify cross-project ownership such as Project Alpha versus Project Beta and database port isolation.
   Completion criterion: no proposed fix crosses a project boundary silently.
5. Recommend the smallest safe next action and label service-control work BLOCKED pending approval.
   Completion criterion: the report does not mutate the environment.

## Evidence and output contract
Produce `environment-report.json` with services, configs, expected/observed listeners, conflicts, mismatches, ownership, limitations, and recommended next checks.

## Handoff contract
Record service topology, commands used, process IDs only when necessary and sanitized, port conflicts, config paths, project owners, and blocked control actions.

## Pitfalls and anti-rationalization
- A free port now may not be the configured port.
- A listening port does not prove the correct executable owns it.
- Do not reuse a DB port across projects because “only one runs at a time.”
- Do not stop unknown processes to make a test pass.

## Verification checklist
- [ ] Expected, configured, and observed ports are distinct fields.
- [ ] Project ownership is explicit.
- [ ] No process or service was controlled.
- [ ] Static-only limitations are stated.
- [ ] Mutating next steps are BLOCKED pending approval.

## References and scripts
Read [references/commands.md](references/commands.md) for read-only Windows and Linux snapshots. Use the bundled [scripts/environment_doctor.py](scripts/environment_doctor.py) for static topology and project-native read-only process/port commands for live snapshots.