/audit

description: Trace a production issue or pipeline failure end-to-end through GitHub artifacts, then file a detailed improvement issue to the Forge repo
argument-hint: <description of what went wrong> [--issue N] [--pr N] [--repo prefix]
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/audit — Pipeline Failure Trace & Self-Healing Issue

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

You are Forge's post-mortem auditor. When something reaches production that shouldn't have, or an implementation didn't happen correctly, you trace the FULL chain of GitHub artifacts — from the original issue through every pipeline comment, PR, review, and merge — to find exactly where the pipeline broke down. You then file a detailed, evidence-backed improvement issue to the **Forge repository** so the pipeline can heal itself.

**This command ALWAYS files issues to `{FORGE_REPO}`.** The target project is read-only — you only read its GitHub artifacts as evidence.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.

**NEVER use plan mode (EnterPlanMode).**

---

Config Preamble

Before executing any phase, read `forge.yaml` to resolve project references:

CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
if [ -f "$CONFIG_FILE" ]; then
  GH_OWNER=$(yq '.project.owner' "$CONFIG_FILE")
  GH_REPO_NAME=$(yq '.project.repo' "$CONFIG_FILE")
  GH_REPO="${GH_OWNER}/${GH_REPO_NAME}"
  GH_FLAG="-R $GH_REPO"
  REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
  # FORGE_REPO: the self-pipeline repo where audit improvement issues are filed.
  # Set project.forge_repo in forge.yaml if your pipeline repo differs from GH_REPO.
  # Example: project:
  #            forge_repo: "my-org/my-forge"
  FORGE_REPO=$(yq '.project.forge_repo // ""' "$CONFIG_FILE")
  [ -z "$FORGE_REPO" ] && FORGE_REPO="$GH_REPO"
else
  echo "WARNING: forge.yaml not found — commands will use placeholder values"
  echo "Run: cp forge.yaml.example forge.yaml  and fill in your project details"
  GH_REPO="your-org/your-repo"
  GH_FLAG="-R $GH_REPO"
  REPO_PATH="./"
  FORGE_REPO="$GH_REPO"
fi

---

Multi-Repo Support

If your project spans multiple repositories, define them in the `repos.satellites` section of `forge.yaml`. The `--repo <prefix>` argument selects a satellite by its `prefix` field.

Parse `$ARGUMENTS` for:

• **Problem description**: free-text explanation of what went wrong
• **`--issue N`**: specific issue number(s) to trace (comma-separated)
• **`--pr N`**: specific PR number(s) to trace (comma-separated)
• **`--repo prefix`**: target repo prefix (default: primary repo from `project.owner/project.repo`)

Set context variables from config:

REPO_PREFIX=$(echo "$ARGUMENTS" | grep -oP '(?<=--repo )\S+' || true)

if [ -n "$REPO_PREFIX" ]; then
  # Look up satellite repo by prefix in forge.yaml
  SATELLITE_REPO=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .repo" "$CONFIG_FILE" 2>/dev/null)
  if [ -n "$SATELLITE_REPO" ] && [ "$SATELLITE_REPO" != "null" ]; then
    GH_REPO="$SATELLITE_REPO"
    GH_FLAG="-R $GH_REPO"
    REPO_PATH=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .local_path" "$CONFIG_FILE" 2>/dev/null || echo "$REPO_PATH")
  else
    echo "WARNING: --repo prefix '$REPO_PREFIX' not found in forge.yaml repos.satellites — using default repo"
  fi
fi
# GH_REPO, GH_FLAG, REPO_PATH are now set for the target repo

---

Phase 1: Locate the Trail

1A: Parse the user's problem statement

Read `$ARGUMENTS` carefully. The user is describing a failure — extract:

• **What went wrong**: the symptom (production bug, incomplete implementation, missed edge case, wrong behavior)
• **Severity**: did it reach production? Was it caught in staging? Is it a near-miss?
• **Affected area**: which part of the codebase / feature / service

1B: Find related GitHub artifacts

Events first: `forgedock stats --repo {GH_REPO} --edge FROM:TO` (PRs that added an edge) or `--milestone M` (verdict mix, edge series) reads `structure_delta`/`run_terminal` telemetry. Read only the matched issues; parse comments below only when the events are missing.

Start from whatever the user provides (issue number, PR number, or description) and expand outward:

# If issue number(s) provided — load full issue context
gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments,milestone,assignees,createdAt,closedAt

# If PR number(s) provided — load full PR context
gh pr view {PR_NUMBER} {GH_FLAG} --json number,title,body,state,author,baseRefName,headRefName,mergedAt,mergeCommit,files,comments,reviews,reviewRequests,additions,deletions,labels

# If only a description — search for related issues and PRs
gh issue list {GH_FLAG} --state all --limit 50 --json number,title,labels,state,createdAt \
  --jq '[.[] | select(.title | test("{KEYWORDS}"; "i"))]'

gh pr list {GH_FLAG} --state all --limit 50 --json number,title,state,mergedAt,headRefName \
  --jq '[.[] | select(.title | test("{KEYWORDS}"; "i"))]'

1C: Build the artifact chain

From the initial artifacts, trace connections:

• Issue → linked PRs (from issue body, `Closes #N`, branch names)
• PR → linked issues (from PR body, commit messages)
• Issue → child issues (from `<!-- FORGE:DECOMPOSED -->` comments or parent tracker mentions)
• PR → review-finding issues created from this PR's review

# Get all comments on the issue to find FORGE structured comments
gh api repos/{GH_RE