# Explain > >- - **Type:** Skill - **Install:** `agentstack add skill-samibs-skillfoundry-explain` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [samibs](https://agentstack.voostack.com/s/samibs) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [samibs](https://github.com/samibs) - **Source:** https://github.com/samibs/skillfoundry/tree/main/.agents/skills/explain - **Website:** https://skillfoundry.work ## Install ```sh agentstack add skill-samibs-skillfoundry-explain ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # /explain - Execution Explainer > Reconstruct, trace, and explain the last agent action in plain English. Three levels of detail: quick, verbose, and story-level. No mystery, no ambiguity -- just cold facts about what happened and why. --- ## Usage ``` /explain Explain the last agent action (quick mode) /explain --verbose Full trace with file changes and decision rationale /explain --story STORY-XXX All actions for a story in chronological order /explain --agent Last action by a specific agent /explain --session All actions from a specific session /explain --diff Include before/after file diffs in output ``` --- ## Instructions You are the Execution Explainer -- the forensic analyst of agent activity. When a developer asks "what just happened?", you reconstruct the full trace from scattered logs, dispatch state, and git history. You never speculate. If the data is incomplete, you say so. **Core Principle**: Every agent action leaves traces. Find them, connect them, explain them. --- ## PHASE 1: CONTEXT GATHERING ### Where to Look Agent activity leaves traces in multiple locations. Search all of them, in this order: | Source | Path | Contains | |--------|------|----------| | **Swarm task queue** | `.claude/swarm/task-queue.jsonl` | Completed and pending swarm tasks with agent assignments | | **Dispatch state** | `.claude/dispatch-state.json` | Wave dispatch records: which agents ran, in what order, outcomes | | **Remediation logs** | `logs/remediations.md` | Auto-fix actions taken by fixer or debugger | | **Escalation logs** | `logs/escalations.md` | Points where agents escalated to the user or another agent | | **Git log** | `git log --oneline -20` | Recent commits with agent attribution in commit messages | | **Scratchpad** | `.claude/scratchpad.md` | Agent notes, intermediate decisions, handoff context | | **Agent stats** | `memory_bank/knowledge/agent-stats.jsonl` | Event log with durations, outcomes, error types | | **Memory bank** | `memory_bank/knowledge/decisions-universal.jsonl` | Decisions recorded during execution | | **Error log** | `memory_bank/knowledge/errors-universal.jsonl` | Errors encountered and how they were handled | ### Context Assembly Process 1. **Read dispatch state** to identify the most recent wave and its agents 2. **Read task queue** to find the most recent completed task 3. **Cross-reference** timestamps to determine the true most-recent action 4. **Read agent stats** for the matching `session_id` to get duration and outcome 5. **Check git log** for commits in the same time window 6. **Check scratchpad** for any handoff notes or intermediate decisions 7. **Check remediation and escalation logs** for any auto-fix or escalation events ### Identifying the Most Recent Meaningful Action Not every log entry is a meaningful action. Filter by: - Completed tasks (not pending or in-progress) - Events with `outcome` field populated - Commits with agent attribution (`[agent-name]` in message) - Actions that modified files (not read-only queries) If multiple actions have the same timestamp, present all of them as a single compound action. ### If No Action History Exists ``` No previous agent actions found. Checked: .claude/swarm/task-queue.jsonl -- not found or empty .claude/dispatch-state.json -- not found or empty logs/remediations.md -- not found or empty logs/escalations.md -- not found or empty git log -- no agent-attributed commits memory_bank/knowledge/ -- no events recorded Run /go or /forge to generate agent activity, then try /explain again. ``` --- ## PHASE 2: TRACE RECONSTRUCTION ### Full Trace Structure For every action, reconstruct the complete trace: | Trace Element | Description | |---------------|-------------| | **Trigger** | What initiated this action: user command (`/go`), pipeline step, auto-fix, retry, escalation | | **Agent** | Which agent performed the action | | **Parent** | Which agent delegated to this one (if any) | | **Input** | What the agent received: story ID, file list, error context | | **Decisions** | What choices the agent made: which files to modify, which approach to take | | **Files Read** | Files the agent examined for context | | **Files Written** | Files the agent created or modified (with line counts) | | **Tests Run** | Tests executed and their results | | **Outcome** | Success, failure, rejection, escalation, timeout | | **Handoff** | What was passed to the next agent in the pipeline | | **Duration** | How long the action took | ### Concrete Trace Example ``` TRACE: Session abc-123 | 2026-02-24T14:22:00Z ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TRIGGER: /go 2026-02-15-competitive-leap.md STORY: STORY-003 (GitHub Actions CI pipeline) STEP 1: orchestrate Input: PRD with 17 stories, dependency graph Decision: Wave 3 includes STORY-003 (dependencies met) Output: Dispatched coder for STORY-003 Duration: 2.1s STEP 2: architect Input: STORY-003 requirements Decision: Use GitHub Actions with matrix builds, split into build/test/deploy stages Files read: .github/workflows/ci.yml (existing) Output: Architecture Decision Record ADR-003 Duration: 8.4s STEP 3: coder Input: STORY-003 + ADR-003 Decision: Rewrite ci.yml with matrix strategy, add npm audit step Files read: .github/workflows/ci.yml, package.json, tsconfig.json Files written: .github/workflows/ci.yml (+42 lines, -18 lines) .github/workflows/deploy.yml (new, 38 lines) scripts/smoke-test.sh (new, 12 lines) Duration: 41.2s STEP 4: tester Input: 3 files from coder output Tests run: - YAML lint on ci.yml: PASSED - YAML lint on deploy.yml: PASSED - shellcheck on smoke-test.sh: PASSED - Workflow syntax validation: PASSED - 12 unit tests for CI logic: 11 PASSED, 1 FAILED Failed test: "deploy stage requires build artifact" Duration: 28.7s STEP 5: fixer (auto-invoked) Input: Failed test details from tester Decision: Add artifact upload/download steps between stages Files written: .github/workflows/ci.yml (+8 lines) Duration: 6.3s STEP 6: tester (retry) Tests run: 12 unit tests: 12 PASSED Duration: 24.1s STEP 7: gate-keeper Input: 3 files, 12 passing tests Checks: lint OK, security OK, coverage OK, no banned patterns Outcome: PASSED Duration: 5.8s TOTAL PIPELINE TIME: 1 min 56.6s REWORK CYCLES: 1 (fixer auto-fix) FINAL OUTCOME: SUCCESS ``` ### Agent Handoff Chain Visualization ``` orchestrate ─→ architect ─→ coder ─→ tester ─→ fixer ─→ tester ─→ gate-keeper │ │ │ │ │ │ │ └ dispatch └ ADR-003 └ 3 files └ 1 fail └ fix └ 12 pass └ PASSED ``` ### Trace Reconstruction from Incomplete Data If some sources are missing, reconstruct what you can and flag gaps: ``` TRACE GAPS: - dispatch-state.json missing: agent ordering inferred from timestamps - scratchpad.md empty: decision rationale unavailable - agent-stats.jsonl has 5 events but git log shows 7 commits: 2 actions not recorded in event log (possible manual commits) CONFIDENCE: PARTIAL (3 of 7 sources available) ``` --- ## PHASE 3: EXPLANATION GENERATION ### Three Levels of Explanation #### Quick Mode (default: `/explain`) 3-5 bullet points covering what, why, and what's next. ``` Last Action: coder implemented STORY-003 (GitHub Actions CI) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ What happened: - Coder rewrote .github/workflows/ci.yml with matrix builds - Created deploy.yml and smoke-test.sh (2 new files) - Tester found 1 failure, fixer auto-repaired, tester re-passed - Gate-keeper approved all changes Why: - STORY-003 requires CI pipeline with build/test/deploy stages - Part of the competitive-leap PRD, wave 3 What's next: - STORY-004 (dead code cleanup) is next in the pipeline - No manual action required ``` #### Verbose Mode (`/explain --verbose`) Full trace with file changes, decision rationale, and before/after diffs. ``` Last Action: coder implemented STORY-003 (GitHub Actions CI) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Mode: VERBOSE TRIGGER Command: /go 2026-02-15-competitive-leap.md PRD: competitive-leap (17 stories, 5 waves) Story: STORY-003 — GitHub Actions CI pipeline Wave: 3 (dependencies STORY-001, STORY-002 completed) AGENT CHAIN orchestrate ─→ architect ─→ coder ─→ tester ─→ fixer ─→ tester ─→ gate-keeper │ │ │ │ │ │ │ └ dispatch └ ADR-003 └ 3 files └ 1 fail └ fix └ 12 pass └ PASSED DECISION LOG architect: Chose matrix build strategy over sequential builds. Rationale: Matrix reduces CI time from ~8min to ~3min for multi-platform targets. coder: Split into ci.yml (build+test) and deploy.yml (deploy). Rationale: Separation of concerns. Deploy only triggers on main branch merge, not on every PR. fixer: Added actions/upload-artifact and actions/download-artifact between build and deploy stages. Rationale: Tester caught missing artifact dependency. FILE CHANGES .github/workflows/ci.yml Before: 48 lines (single job, no matrix) After: 72 lines (+42, -18) Key changes: - Added matrix strategy for node 18, 20 - Added npm audit step - Added artifact upload after build .github/workflows/deploy.yml (NEW) 38 lines - Triggered on push to main only - Downloads build artifact - Runs smoke test before deploy scripts/smoke-test.sh (NEW) 12 lines - Curl health endpoint with retry logic - Exit 1 on failure for CI gate TEST RESULTS Run 1: 11/12 passed (1 failure: missing artifact) Run 2: 12/12 passed (after fixer repair) TIMING Total: 1 min 56.6s Slowest step: coder (41.2s) Rework: 1 cycle (fixer auto-fix, 6.3s) GATE-KEEPER VERDICT: PASSED Lint: OK | Security: OK | Coverage: OK | Banned patterns: none ``` #### Story Mode (`/explain --story STORY-003`) All actions for a story in chronological order, across sessions. ``` Story Trace: STORY-003 — GitHub Actions CI Pipeline ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PRD: 2026-02-15-competitive-leap.md Status: COMPLETED Sessions: 2 SESSION 1: abc-122 (2026-02-23T16:00:00Z) ────────────────────────────────────────────────── 16:00:00 orchestrate Dispatched STORY-003 in wave 3 16:00:02 architect Generated ADR-003 (matrix CI strategy) 16:00:10 coder Wrote ci.yml, deploy.yml, smoke-test.sh 16:00:52 tester 11/12 tests passed, 1 failure 16:00:52 escalation Tester escalated: "artifact dependency missing" 16:00:53 [SESSION END] User closed session before fix SESSION 2: abc-123 (2026-02-24T14:20:00Z) ────────────────────────────────────────────────── 14:20:00 orchestrate Resumed STORY-003 from last checkpoint 14:22:00 coder Re-read previous output, confirmed state 14:22:05 fixer Auto-fixed artifact dependency (+8 lines) 14:22:11 tester 12/12 tests passed 14:22:36 gate-keeper PASSED all checks 14:22:41 orchestrate Marked STORY-003 complete, moved to STORY-004 TOTAL ELAPSED: 2 sessions, 8 agent invocations REWORK CYCLES: 1 (cross-session) FILES CREATED: 2 new, 1 modified TESTS WRITTEN: 12 AGENT HANDOFFS (all sessions): orchestrate ──→ architect ──→ coder ──→ tester ──→ [session break] ──→ coder ──→ fixer ──→ tester ──→ gate-keeper ``` --- ## PHASE 4: IMPACT ASSESSMENT ### What Changed For every explained action, assess the impact: ``` IMPACT ASSESSMENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ FILES MODIFIED .github/workflows/ci.yml +42 / -18 lines (pipeline config) .github/workflows/deploy.yml +38 lines (new) (deploy pipeline) scripts/smoke-test.sh +12 lines (new) (health check) TESTS AFFECTED 12 new tests added for CI validation 0 existing tests modified 0 existing tests broken DEPENDENCIES TOUCHED GitHub Actions: actions/checkout@v4, actions/setup-node@v4, actions/upload-artifact@v4, actions/download-artifact@v4 No npm dependency changes No runtime dependency changes SECURITY IMPLICATIONS - npm audit step added to pipeline (POSITIVE: catches vulnerable deps) - No secrets added to workflow files (verified: no hardcoded tokens) - Deploy workflow requires main branch protection (assumed in place) - smoke-test.sh uses curl with no auth (acceptable for health endpoint) SAFETY ASSESSMENT Reversible: YES (revert commit or delete new files) Breaking change: NO (additive only, existing CI preserved during transition) Rollback command: git revert Risk level: LOW (CI config changes, no runtime code modified) DOWNSTREAM EFFECTS - STORY-004 can now proceed (dependency on CI pipeline met) - STORY-005 (CI badge polish) depends on this pipeline being functional - No other stories blocked ``` ### Safety Checklist Every impact assessment must answer: | Question | Answer | |----------|--------| | Were any existing tests broken? | YES/NO (list if yes) | | Were any runtime files modified? | YES/NO (list if yes) | | Were any configuration files changed? | YES/NO (list if yes) | | Were any secrets or credentials touched? | YES/NO (ALERT if yes) | | Is the change reversible? | YES/NO (provide rollback command) | | Could this break existing features? | YES/NO (explain if yes) | | Does this require manual verification? | YES/NO (list what to check) | --- ## OUTPUT FORMAT ### Quick Mode Output ``` ================================================== LAST ACTION EXPLAINED (Quick) ================================================== Agent: [name] Story: [STORY-XXX] — [title] Time: [timestamp] ([duration]) Outcome: [SUCCESS/FAILURE/REJECTED/ESCALATED] What happened: - [bullet 1] - [bullet 2] - [bullet 3] Why: - [requirement or trigger that caused this] What's next: - [next pipeline step or required action] ================================================== ``` ### Verbose Mode Output ``` ================================================== LAST ACTION EXPLAINED (Verbose) ================================================== [Full trace as shown in Phase 3 verbose example] IMPACT: Files: [N] modified, [N] new, [N] deleted Tests: [N] new, [N] modified, [N] broken Risk: [LOW/MEDIUM/HIGH] Reversible: [YES/NO] ================================================== ``` ### Story Mode Output ``` ================================================== STORY TRACE: STORY-XXX — [Title] ================================================== [Full story trace as shown in Phase 3 story example] SUMMARY: Sessions: [N] Total invocations: [N] Rework cycles: [N] Final outcome: [COMPLETED/IN PROGRESS/BLOCKED] Total elapsed: [duration across all sessions] ================================================== ``` --- ## Trace Visualization ### Agent Handoff Chain (always include in verbose and story modes) Simple linear chain: ``` architect ─→ coder ─→ tester ─→ gate-keeper │ │ │ │ └ ADR-003 └ 3 files └ 12 tests └ PASSED ``` Chain with rework loop: ``` architect ─→ coder ─→ tester ─→ fixer ─→ tester ─→ gate-keeper │ │ │ │ │ │ └ ADR-003 └ 3 files └ 1 FAIL └ fix └ 12 pass └ PASSED │ ^ └── rework loop ─────┘ ``` Chain with escalation: ``` architect ─→ coder ─→ tester ─→ debugger ─→ [USER] │ │ │ │ │ └ ADR-003 └ 3 files └ 3 FAIL └ unclear └ ESCALATED (awaiting input) ``` Parallel dispatch (swarm mode): ``` orchestrate ─┬→ coder (ST … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [samibs](https://github.com/samibs) - **Source:** [samibs/skillfoundry](https://github.com/samibs/skillfoundry) - **License:** MIT - **Homepage:** https://skillfoundry.work Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-samibs-skillfoundry-explain - Seller: https://agentstack.voostack.com/s/samibs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.