---
name: app-pipeline-inspector
description: Use when adding reusable pipeline/trace inspectors to apps with prompt chains, AI context stacks, model/tool calls, generated images, videos, briefs, or multi-step agent workflows.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [pipeline, inspector, traceability, prompts, ai-apps, ui, sqlite]
    related_skills: [coding-quality-workflow, vps-app-deployment]
---

# App Pipeline Inspector

## Overview

Use this skill to add the Hermes-style vertical pipeline inspector to any app Alex builds. The goal is not only a pretty diagram: it is a durable debugging surface for prompt chains, injected context, model/tool choices, decisions, retries, and generated outputs.

The canonical pattern came from the astrology reading pipeline diagram and the Hermes Creative pipeline inspector. It should be portable, but each app can define domain-specific stages and entity links.

## When to Use

Use for apps that have any of these:

- Multi-step AI generation flows.
- Prompt chains or context stacks.
- Model/tool/provider decisions.
- Images, video clips, audio, scripts, briefs, scenes, shots, or other generated artifacts.
- UI surfaces where Alex already inspects prompts/models and wants a full flow view.

Do not use this as a replacement for logs. Logs are chronological; the pipeline inspector is entity-centered and shows “what produced this thing?”

## Durable Data Contract

Prefer a normalized append-only trace table. SQLite example:

```sql
CREATE TABLE IF NOT EXISTS pipeline_trace_events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  project_id INTEGER,
  entity_type TEXT NOT NULL,
  entity_id INTEGER,
  trace_group TEXT,
  stage_key TEXT NOT NULL,
  stage_label TEXT NOT NULL,
  stage_order INTEGER DEFAULT 0,
  status TEXT DEFAULT 'recorded',
  summary TEXT,
  input_json TEXT,
  prompt_json TEXT,
  model_tool_json TEXT,
  decision_json TEXT,
  output_json TEXT,
  artifact_url TEXT,
  parent_event_id INTEGER,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
);
```

Recommended entity types:

- `creative_brief`
- `reference_image`
- `shot_frame`
- `video_clip`
- `script`
- `scene`
- `shot`
- app-specific nouns as needed

Recommended JSON buckets:

- `input_json`: user request, entity state, source assets, upstream outputs.
- `prompt_json`: exact prompt text, prompt fragments, system/developer context, negative prompt, reference list.
- `model_tool_json`: provider, model, endpoint/tool, parameters, caps, fallback chain, cost estimate.
- `decision_json`: routing choices, selected references, retry/fallback reasons, safety/moderation result, approval gate.
- `output_json`: provider response, parsed result, created DB rows, artifact URLs, downstream handoff packet.

## Recording Pattern

1. Add a small server helper, for example `recordPipelineTrace(db, event)`.
2. Record before/at the start of a generation with the exact input and prompt payload.
3. Record completion/failure with provider response, created artifact IDs/URLs, errors, and retry decisions.
4. Link trace events to the artifact entity that Alex will inspect later.
5. For generated artifacts, store trace rows even if the app also stores prompts directly on the artifact row.
6. Do not log secrets. Redact API keys, auth headers, cookies, signed URLs if needed, and PII unless user-provided content is essential to the prompt.

## API Pattern

Expose an entity-centered route:

```http
GET /api/projects/:projectId/pipeline-trace?entity_type=shot_frame&entity_id=123
```

Response shape:

```json
{
  "events": [
    {
      "id": 1,
      "stage_key": "frame_prompt",
      "stage_label": "Frame prompt assembled",
      "stage_order": 30,
      "status": "completed",
      "summary": "Built first-frame prompt with character/set refs",
      "input": {},
      "prompt": {},
      "model_tool": {},
      "decision": {},
      "output": {},
      "artifact_url": "/uploads/...png",
      "created_at": "..."
    }
  ]
}
```

Use typed parsed JSON in the API response; keep raw JSON text only in SQLite.

## UI Pattern

- Add a compact topbar icon for global/project pipeline inspection when useful.
- Add contextual **Pipeline** or **Inspect pipeline** buttons beside existing prompt/model inspect actions.
- Open a full-screen or right-side inspector view rather than cramming the diagram inline.
- Use a vertical scrolling node chain ordered by `stage_order` then timestamp.
- Nodes are collapsible.
- Inside each node, sections are also collapsible: Input, Prompt, Model/Tool, Decision, Output.
- JSON must use an interactive tree viewer: collapsible objects/arrays, colored keys and primitive values, wrapping long strings, and small previews like `{6}` or `[12]`.
- Large prompt strings should be readable as wrapped text, not one-line JSON sludge.
- For durable agent/developer jobs, running cards must visibly animate, open into an entity-scoped live session inspector, stream real tool/progress output, and retain the transcript after completion. Keep lifecycle state separate from raw logs. See `references/live-agent-run-inspector.md` for the API, redaction, recovery, accessibility, mobile, and browser-verification pattern.
- When those workers also create, change, build, deploy, or remove project artifacts, reconcile a bounded versioned manifest into canonical domain state and make canvas-node inspectors actionable. See `references/agent-artifact-canvas-projection.md` for stable keys, tombstones, cross-process freshness, truthful deployment status, provenance, and verification.

## App-Specific Adaptation

Each app should define its own stage map. Example for video-story:

1. Creative import / project brief context.
2. Script / treatment generation.
3. Scene definition.
4. Shot breakdown.
5. Reference bundle assembly.
6. Frame prompt assembly.
7. Image provider call and retry/fallback decisions.
8. Video prompt/provider call.
9. Lip-sync/export decisions.
10. Final artifact output.

Do not force every entity to show every stage. If Alex inspects a shot frame, show the upstream events that matter to that frame. If he inspects a final video, show clip/frame/export events.

See `references/video-story-first-slice-2026-05-31.md` for the first deployed Video Story adaptation: entity scopes, UI entry points, table/API shape, and follow-up trace depths.

## Verification Checklist

- [ ] Trace table exists and migrations are idempotent.
- [ ] At least one real generation path writes trace events before and after provider calls.
- [ ] API returns parsed JSON and does not expose secrets.
- [ ] Contextual UI buttons open the inspector scoped to the selected entity.
- [ ] Nodes and sections collapse independently.
- [ ] JSON tree handles nested objects, arrays, nulls, booleans, long strings, and malformed legacy JSON safely.
- [ ] Product/surface/infra inspectors expose URLs, source, status, and provenance, while Developer inventory tabs distinguish built source from verified deployments and registered databases with explicit truthful empty states.
- [ ] Build/tests pass.
- [ ] Live health and route smoke tests pass after deploy.

## Common Pitfalls

1. **Only showing the terminal artifact event.** If an inspected frame/video/brief only shows the final prompt/output, Alex cannot see how the description, context stack, or prompt was created. Always include upstream lineage nodes when available: project/brief context → scene/script/shot breakdown → reference/context stack → prompt assembly → provider call/output.
2. **Only reconstructing from current rows.** That helps old artifacts, but the durable version needs timestamped trace snapshots captured when the work happened.
3. **Ambiguous “Input” vs “Prompt” labels.** Label and explain them clearly: Inputs/context are source data available at that stage; Prompt/message is the assembled text or structured payload produced from those inputs and sent onward.
4. **Raw `<pre>` JSON everywhere.** Alex needs collapsible and colored JSON trees because prompts and payloads are large.
5. **Forgetting failures.** Failed provider calls, moderation blocks, and fallback choices are often the most useful pipeline events.
6. **Global-only inspector.** The most useful entry points are contextual: brief, frame, reference image, shot, or video.
7. **Secret leakage.** Redact auth headers, API tokens, signed URLs, and provider keys before persistence or display.
8. **Blank filtered infrastructure tabs.** A repository can exist while exact `deployment` and `database` filters return zero rows. Show built source awaiting deployment and explicit reasons for missing deployment/database records; never hide the repository or synthesize live infrastructure to fill the screen.