inspect
Inspect a running service's runtime state — exercise API endpoints, verify internal state via backoffice, and validate the UI via browser. Spec-driven.
SKILL.mdskills/inspect/SKILL.md
GitHubUser Input
You MUST consider the user input before proceeding (if not empty).
Purpose
This command inspects a running service at runtime. It exercises API
endpoints, verifies internal state through backoffice tools, and validates the
UI through browser tools — all driven by the feature specification. No
compilation or unit tests happen here; use /akka:build for that.
Outline
Pre-flight checks:
- Call
akka_local_statusto verify the service is running. If not running, stop and tell the user: "No service is running locally. Run/akka:buildfirst to compile, test, and start the service." - Call
akka_sdd_list_specsto find the target feature. If the user specified a feature name inthe user's request, match it. Otherwise, if there is exactly one feature, use it. If multiple features exist, ask the user which to inspect. - If no spec exists, stop and tell the user: "No feature specification
found. Run
/akka:specifyfirst to create one, or provide a feature name." - Read the spec.md for the target feature. Extract:
- API endpoints (paths, methods, expected request/response shapes)
- Entities and their expected events/state
- Workflows and expected step sequences
- Views and expected query results
- Agents and expected behavior
- Acceptance criteria to verify
- Call
Discover components: Call
akka_backoffice_list_componentswithlocal=trueto list all components registered in the running service.- Compare against what the spec defines — flag any components that are missing from the running service or present but not in the spec
- Report the component inventory: entities, views, workflows, agents, endpoints
Exercise API endpoints: For each endpoint defined in the spec, use
akka_local_requestto send requests and verify responses:- Happy path: Send valid requests matching the spec's examples or acceptance criteria. Verify HTTP status codes and response payloads.
- Command operations: POST/PUT/DELETE commands that mutate state. Execute these in the order that makes sense (e.g. create before update).
- Query operations: GET requests to read state back. Verify the response matches what the commands should have produced.
- Error cases: If the spec defines error scenarios (invalid input, not-found, conflict), test those too. Verify appropriate error responses.
- Record all request/response pairs for the report.
Verify internal state: After exercising the API, use backoffice tools with
local=trueto verify the service internals are consistent:- Entity state:
akka_backoffice_get_entity_state— verify entity state matches what the API commands should have produced - Event journal:
akka_backoffice_list_events— verify event-sourced entities have the expected events in the correct order - Workflows:
akka_backoffice_get_workflow— verify workflow steps executed with expected status and state transitions - Views:
akka_backoffice_query_view— verify view projections return expected data after entity state changes - Agents:
akka_backoffice_list_agent_interactions— review agent tool calls, model responses, and guardrail behavior - Timers:
akka_backoffice_list_timers— verify expected timers are registered - Use
akka_backoffice_describe_viewto understand view schemas before querying - Use pagination (
page_size,page_token) for large result sets
- Entity state:
Browser inspection (only if the spec defines a web UI served by the service). Skip this step entirely if the service only exposes API endpoints — use
akka_local_requestin step 3 for those.akka_browser_navigateto open the service's UI endpoint (e.g.http://localhost:<port>/ui— use the port and path from the spec or fromakka_local_status)akka_browser_screenshotto capture the visual stateakka_browser_snapshotto verify text contentakka_browser_clickandakka_browser_fillto interact with forms and buttons as described in the specakka_browser_evalfor advanced JavaScript inspection if needed- Cross-reference: verify that what the UI shows matches entity/view state from step 4. For example, if a view query returns 3 items, the UI should render 3 items.
akka_browser_closewhen done to release browser resources
Report: Summarize inspection findings organized by the spec's acceptance criteria:
- For each acceptance criterion: pass or fail with evidence (request/response payloads, entity state snapshots, event journals, screenshots)
- Component inventory: all registered vs expected
- API endpoint results: status codes, response validation
- Internal state consistency: entity state, events, workflow steps, views
- Browser findings: UI screenshots, interaction results
- Issues found: list anything that doesn't match the spec, with severity (blocker / warning / observation)
- Next steps: suggest
/akka:implementfor fixes,/akka:reviewfor code review, or/akka:deployif everything passes
Error Handling
- If the service crashes during inspection (endpoint returns connection refused
after previously working), check
akka_local_logswithsource: "service"for the crash reason. Report it and suggest/akka:buildto restart. - If a backoffice tool returns an error, report the specific error and continue inspecting other components — don't stop the whole inspection for one failure.
- If the browser fails to launch (Chrome not found), skip browser inspection and note it in the report. The backoffice and API inspection results are still valuable.
Key Rules
- This is INSPECTION ONLY — do not modify code, configuration, or service state beyond what the API calls naturally produce
- Always use
local=trueon all backoffice tool calls - Exercise endpoints in a logical order (create before read/update/delete)
- Report failures with evidence, not just "it failed"
- If the spec is vague about expected behavior, state what you observed and ask the user whether it matches their intent
Done When
-
akka_local_statusconfirmed the service is running (or the command stopped and told the user to run/akka:buildfirst). -
akka_sdd_list_specsresolved a single target feature — matched bythe user's request, auto-selected when only one exists, or explicitly chosen by the user — and itsspec.mdwas read (or the command stopped and told the user to run/akka:specify). - The spec was parsed for API endpoints, entities, workflows, views, agents, and acceptance criteria before any tool calls were made.
-
akka_backoffice_list_components(local=true) produced a component inventory; any component present in the spec but missing at runtime — or present at runtime but not in the spec — was flagged. - Every API endpoint defined in the spec was exercised via
akka_local_requestin a logical order (create before read/update/delete), covering happy-path, command, query, and any spec-defined error cases; each request/response pair was recorded for the report. - Internal state was verified against the API's effects using backoffice tools with
local=true: entity state (akka_backoffice_get_entity_state), event journals (akka_backoffice_list_events), workflow steps (akka_backoffice_get_workflow), view projections (akka_backoffice_query_view), agent interactions (akka_backoffice_list_agent_interactions), and timers (akka_backoffice_list_timers) — with pagination when needed. - Browser inspection ran only if the spec defines a web UI; when it ran,
akka_browser_screenshot,akka_browser_snapshot, and interaction tools captured the UI state and cross-referenced it with view/entity state, andakka_browser_closewas called at the end. When the spec has no UI, this step was explicitly skipped. - NO code, configuration, or service state was modified beyond what the exercised API calls naturally produced (this is inspection only).
- Every backoffice call used
local=true; runtime crashes were reported with a link toakka_local_logsoutput rather than silently swallowed. - The final report organizes findings by the spec's acceptance criteria (each pass/fail with evidence), lists the component inventory, API endpoint results, internal-state consistency, browser findings, issues (blocker / warning / observation), and a next-step recommendation (
/akka:implement,/akka:review, or/akka:deploy).