analyse

<objective>

Analyze GitHub threads + repo vitality. Help maintainers triage, respond, decide fast. Output actionable + structured — not just summaries.

NOT for implementing PR action items (use oss:resolve). NOT for multi-agent code review (use oss:review). NOT for CI pipeline diagnosis (use oss:cicd-steward (requires oss plugin)).

</objective>

<inputs>

• $ARGUMENTS: one of:
• N (number, plain 123 or #123) — any GitHub thread: issue, PR, or discussion; auto-detects type
• vitality [<owner>/<repo> | <github-url>] — repo vitality overview with 9-axis health scorecard and duplicate detection. Optional repo argument accepts owner/repo shorthand or full https://github.com/owner/repo URL. When omitted, auto-detected from git upstream. Non-GitHub remotes (GitLab, Bitbucket, etc.) stop with warning.
• ecosystem — downstream consumer impact analysis for library maintainers
• --reply — only valid with N; spawns shepherd to draft contributor-facing reply after thread analysis. Silently ignored for vitality and ecosystem.
• path/to/report.md — path to existing report file; only valid combined with --reply; skips all analysis, spawns shepherd directly using provided file

</inputs>

<constants>

<!-- Background agent health monitoring (CLAUDE.md §6) — applies to Step 7 shepherd spawn --> MONITOR_INTERVAL=300 # 5 minutes between polls HARD_CUTOFF=900 # 15 minutes of no file activity → declare timed out EXTENSION=300 # one +5 min extension if output file explains delay

</constants>

<workflow>

<!-- Agent resolution: see _OSS_SHARED/agent-resolution.md -->

Agent Resolution

# Cold-start fallback (sets $_OSS_SHARED — run this first):
_OSS_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/oss}/bin/resolve_shared_path.py" oss skills/_shared 2>/dev/null)  # timeout: 5000
FOUNDRY_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/oss}/bin/resolve_shared_path.py" foundry skills/_shared 2>/dev/null)  # timeout: 5000 — loads: terminal-summaries.md (from foundry plugin _shared/)

loads: oss-shared-resolver.md

Then: Read $_OSS_SHARED/oss-shared-resolver.md and execute its contents

Step 1: Flag parsing

REPLY_MODE=false
CLEAN_ARGS=$ARGUMENTS
if [[ "$ARGUMENTS" == *"--reply"* ]]; then
    REPLY_MODE=true
    CLEAN_ARGS=$(echo "$ARGUMENTS" | sed 's/ --reply\b//')
    CLEAN_ARGS="${CLEAN_ARGS#"${CLEAN_ARGS%%[![:space:]]*}"}"
fi # timeout: 5000

# Strip leading '#' so both '123' and '#123' work
CLEAN_ARGS="${CLEAN_ARGS#\#}"

REPLY_MODE only meaningful when $CLEAN_ARGS is number — silently ignored for vitality and ecosystem.

DIRECT_PATH_MODE=false
# Exclude vitality/ecosystem prefix (*.md check must not intercept them) and plan/todo files
if [[ "$CLEAN_ARGS" == *.md ]] && [[ "$CLEAN_ARGS" != vitality* ]] && [[ "$CLEAN_ARGS" != ecosystem* ]]; then
    if [[ "$CLEAN_ARGS" == .plans/* ]] || [[ "$CLEAN_ARGS" == *todo_*.md ]]; then
        echo "! Invalid report path: '$CLEAN_ARGS' — plan/todo files are not valid report paths."
        echo "Usage: /oss:analyse <path/to/report.md> --reply  (use a .reports/ path)"
        exit 1
    fi
    DIRECT_PATH_MODE=true
    REPORT_FILE="$CLEAN_ARGS"
fi # timeout: 5000
TODAY=$(date +%Y-%m-%d)

DIRECT_PATH_MODE=true only valid when REPLY_MODE=true — if combined without --reply, Step 2 prints plain-text error and stops; execution never reaches Step 5 mode dispatch.

# --- Vitality mode: resolve target repo ---
GH_OWNER=""
GH_REPO=""
if [[ "$CLEAN_ARGS" == vitality* ]]; then
    VITALITY_EXTRA="${CLEAN_ARGS#vitality}"
    VITALITY_EXTRA="${VITALITY_EXTRA# }"  # trim leading space

    if [ -n "$VITALITY_EXTRA" ]; then
        # Argument provided — URL or owner/repo
        if [[ "$VITALITY_EXTRA" =~ ^https?:// ]]; then
            if [[ "$VITALITY_EXTRA" != *"github.com"* ]]; then
                echo "⚠ Not a GitHub URL — this skill supports GitHub only."
                echo "Other providers (GitLab, Bitbucket, Azure DevOps) are not supported."
                echo "Usage: /oss:analyse vitality https://github.com/owner/repo"
                exit 0
            fi
            VITALITY_REPO=$(echo "$VITALITY_EXTRA" | sed 's|https\?://github\.com/||' | cut -d'/' -f1-2)  # timeout: 5000
        elif [[ "$VITALITY_EXTRA" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
            VITALITY_REPO="$VITALITY_EXTRA"
        else
            echo "⚠ Unrecognised vitality argument: '$VITALITY_EXTRA'"
            echo "Usage: /oss:analyse vitality [owner/repo | https://github.com/owner/repo]"
            exit 0
        fi
    else
        # No argument — detect from gh context or git remote
        VITALITY_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)  # timeout: 10000
        if [ -z "$VITALITY_REPO" ]; then
            REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")  # timeout: 5000
            if [[ "$REMOTE_URL" == *"github.com"* ]]; then
                VITALITY_REPO=$(echo "$REMOTE_URL" | sed 's|.*github\.com[:/]||' | sed 's|\.git$||')  # timeout: 5000
            elif [ -n "$REMOTE_URL" ]; then
                echo "⚠ Remote '$REMOTE_URL' is not a GitHub repository."
                echo "This skill supports GitHub only. Other providers are not supported."
                echo "Tip: /oss:analyse vitality https://github.com/owner/repo"
                exit 0
            else
                echo "⚠ No GitHub repository detected. Pass a URL:"
                echo "  /oss:analyse vitality https://github.com/owner/repo"
                exit 0
            fi
        fi
    fi
    GH_OWNER=$(echo "$VITALITY_REPO" | cut -d'/' -f1)  # timeout: 5000
    GH_REPO=$(echo "$VITALITY_REPO" | cut -d'/' -f2)  # timeout: 5000
    CLEAN_ARGS="vitality"  # normalise for mode dispatch
fi

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS for any remaining --<token> tokens. If found: invoke AskUserQuestion with:

• question: "Unknown flag(s): --<token>. Supported: --reply. How to proceed?"
• (a) Abort — re-invoke with correct flags
• (b) Continue ignoring unknown flags

Step 2: Reply-mode fast-path (only when REPLY_MODE=true)

Skip when REPLY_MODE=false and DIRECT_PATH_MODE=false.

Direct report path (DIRECT_PATH_MODE=true — checked first):

• REPLY_MODE=false → print: "A report path was passed without --reply. Did you mean /analyse <path.md> --reply? Re-run with --reply to continue, or use /analyse <N> | vitality | ecosystem." and stop.
• REPLY_MODE=true and file missing ([ ! -f "$REPORT_FILE" ]) → print Error: report not found: $REPORT_FILE and stop.
• REPLY_MODE=true and file exists → print [direct] using $REPORT_FILE → skip to Step 7. Don't run auto-detection fast-path below.

Remaining fast-path logic (TODAY, REPORT_FILE auto-construction, drift check) only runs when DIRECT_PATH_MODE=false.

When REPLY_MODE=true, check if fresh report already exists before any API calls:

# REPORT_FILE assigned here only for numeric (thread) mode.
# vitality/ecosystem modes: REPORT_FILE set inside modes/vitality.md and modes/ecosystem.md respectively.
# DIRECT_PATH_MODE: REPORT_FILE already set from $CLEAN_ARGS above.
SUBDIR="thread"  # default for numeric args; overridden for health/ecosystem in their mode files
REPORT_FILE=".reports/analyse/$SUBDIR/output-analyse-$SUBDIR-$CLEAN_ARGS-$TODAY.md"
DRIFT=false
FAST_PATH=false
FAST_PATH_TENTATIVE=false

if [ -f "$REPORT_FILE" ]; then
    REPORT_MTIME=$(stat -f %m "$REPORT_FILE" 2>/dev/null || stat -c %Y "$REPORT_FILE")  # timeout: 5000
    FAST_PATH_TENTATIVE=true  # drift check deferred to Step 4 — type must be known first
fi
# Persist across Bash calls (Check 41: fresh shell loses vars)
echo "$DRIFT" > "${TMPDIR:-/tmp}/analyse-drift"
echo "$FAST_PATH" > "${TMPDIR:-/tmp}/analyse-fast-path"
echo "$FAST_PATH_TENTATIVE" > "${TMPDIR:-/tmp}/analyse-fast-path-tentative"
e