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.md

GitHub

User 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

  1. Pre-flight checks:

    • Call akka_local_status to verify the service is running. If not running, stop and tell the user: "No service is running locally. Run /akka:build first to compile, test, and start the service."
    • Call akka_sdd_list_specs to find the target feature. If the user specified a feature name in the 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:specify first 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
  2. Discover components: Call akka_backoffice_list_components with local=true to 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
  3. Exercise API endpoints: For each endpoint defined in the spec, use akka_local_request to 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.
  4. Verify internal state: After exercising the API, use backoffice tools with local=true to 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_view to understand view schemas before querying
    • Use pagination (page_size, page_token) for large result sets
  5. 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_request in step 3 for those.

    • akka_browser_navigate to open the service's UI endpoint (e.g. http://localhost:<port>/ui — use the port and path from the spec or from akka_local_status)
    • akka_browser_screenshot to capture the visual state
    • akka_browser_snapshot to verify text content
    • akka_browser_click and akka_browser_fill to interact with forms and buttons as described in the spec
    • akka_browser_eval for 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_close when done to release browser resources
  6. 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:implement for fixes, /akka:review for code review, or /akka:deploy if everything passes

Error Handling

  • If the service crashes during inspection (endpoint returns connection refused after previously working), check akka_local_logs with source: "service" for the crash reason. Report it and suggest /akka:build to 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=true on 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_status confirmed the service is running (or the command stopped and told the user to run /akka:build first).
  • akka_sdd_list_specs resolved a single target feature — matched by the user's request, auto-selected when only one exists, or explicitly chosen by the user — and its spec.md was 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_request in 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, and akka_browser_close was 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 to akka_local_logs output 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).