agentic-runtime-debug-loop

name	agentic-runtime-debug-loop
description	Use when debugging a deployed service/profile, investigating CI or Kubernetes runtime failure, explaining deployment drift, or producing a runtime debug session summary

Agentic Runtime Debug Loop

Use this skill when debugging a deployed service/profile and a bounded evidence loop is needed across code, CI/CD, Kubernetes, artifacts, logs, Grafana observability, and Phase 4 runtime resources.

Phase 6.8A Delegation

For product-level diagnostics, construct a HarnessEvidenceRequest and use agentic-harness-evidence-loop / agentic-evidence to collect the local bundle and produce RepairRoute.

This skill retains service/profile collector knowledge for runtime evidence input, but it is not the product-level evidence loop contract. Do not execute code-changing repair, Git mutation, CI trigger, deploy, rollback, Control Plane writes, or storage upload from this skill.

Inputs

Required:

• service
• profile
• plan

If service, profile, or plan is missing, ask for it before starting the session or running remote commands. If a controlled write action may be needed, the plan must contain an agentic_debug_loop fenced YAML block.

Plan Policy

Read the implementation plan before remote commands. The policy shape is:

agentic_debug_loop:
  max_iterations: 3
  success_criteria:
    - "Kubernetes pods for app-api are ready"
    - "latest CI pipeline succeeds"
  allowed_actions:
    - jenkins.build
    - gitlab.run_pipeline
    - kubernetes.rollout_restart
  allowed_resources:
    - main-postgres
    - main-redis

No agentic_debug_loop block means one read-only iteration. Do not execute write actions without explicit allowed_actions.

Session Commands

Start a session:

bin/agentic-runtime --json loop start --service <service> --profile <profile> --plan <plan>

Record each material command:

bin/agentic-runtime --json loop record-step --session <session-id> --kind status --status ok --summary "<short summary>" --evidence <path>

Finish after writing the runtime summary:

bin/agentic-runtime --json loop finish --session <session-id> --final-status <fixed|likely_fixed|not_fixed|blocked|error> --summary-path <summary-path>

Session records are written under .generated/runtime/debug-sessions/.

Workflow

1. Parse the plan policy and start a debug session.
2. Run local-only checks:

   bin/agentic-runtime --json status --service <service> --profile <profile> --local-only
   bin/agentic-runtime --json correlate --service <service> --profile <profile> --local-only
   

3. Run remote read-only evidence commands:

   bin/agentic-runtime --json status --service <service> --profile <profile>
   bin/agentic-runtime --json correlate --service <service> --profile <profile>
   bin/agentic-runtime --json observe doctor --service <service> --profile <profile>
   bin/agentic-runtime --json observe metrics --service <service> --profile <profile>
   bin/agentic-runtime --json observe logs --service <service> --profile <profile>
   bin/agentic-runtime --json observe trace --service <service> --profile <profile> --trace-id <trace-id>
   

4. Inspect evidence in this order:
   • config/parameter resolution
   • CI status and logs
   • artifact existence and digest/tag
   • deployed Kubernetes image
   • Kubernetes pod state, events, and logs
   • Grafana observability metrics, logs, dashboard links, and trace hints
   • configured debug_loop resource hints
5. If status, logs, or correlate evidence includes a trace id or request id, run trace lookup before Phase 4 resource checks:

   bin/agentic-runtime --json observe trace --service <service> --profile <profile> --trace-id <trace-id>
   

   Record the result with --kind observability.
6. Record observability commands with --kind observability and evidence paths under .generated/runtime/observability/.
7. When evidence points to a data or middleware issue, run resource doctor before query or inspect:

   bin/agentic-runtime --json resource doctor --target <resource-id>
   

8. Query or inspect only resources allowed by the plan and service/profile config.
9. Search code/config only after evidence points to a likely area.
10. If a controlled action is authorized, run dry-run before confirm:

bin/agentic-runtime --json act --service <service> --profile <profile> --action <action> --plan <plan> --dry-run

Inspect the dry-run target, parameters, risk, and confirmation id. Run --confirm only when the action is listed in allowed_actions and the plan policy unambiguously authorizes automated confirmation for the current loop. If that authorization is absent or ambiguous, stop and ask for a plan update or human direction.

bin/agentic-runtime --json act --service <service> --profile <profile> --action <action> --plan <plan> --confirm <confirmation-id>

11. Re-observe status if iterations remain.
12. Write the runtime summary and finish the session.

Stop Conditions

• Stop when success criteria are met.
• Stop when max_iterations is exhausted.
• Stop when required secrets, kubeconfig, or runtime config are missing.
• Stop when Grafana observability is configured but its required secret env vars are missing.
• Stop when an unlisted action or resource is needed.
• Stop when Phase 4 resource safety blocks the operation.
• Stop if evidence is contradictory; summarize the contradiction and ask for human direction.