survey-history

name	survey-history
description	Investigate git history, docs/history.md, and GitHub issue/PR timeline since the relevant issue opened, to surface changes that may invalidate the issue's premises.
model	sonnet
user-invocable	false

Investigate the project's git history and GitHub issue/PR timeline to detect changes made after the relevant issue was opened that might invalidate its premises.

Procedure

Step 0 — Resolve <PLANS_DIR>

Before any tool call below that references <PLANS_DIR>, run the following Bash command exactly once:

PLANS_DIR=$(bash "$AGENTS_CONFIG_DIR/bin/workflow-plans-dir" 2>/dev/null \
              || printf '%s\n' "${WORKFLOW_PLANS_DIR:-$HOME/.workflow-plans}")
printf 'PLANS_DIR=%s\n' "$PLANS_DIR"

Capture the printed absolute path and substitute it for every <PLANS_DIR> placeholder in the remainder of this SKILL.md. Subagent prompts must receive the resolved absolute path as a literal string (subagents cannot expand $VAR). Reuse across all subsequent steps in this skill invocation — do not re-resolve.

When invoked as a parallel Agent subagent by workflow-init, the orchestrator passes artifact_path and context_path as resolved absolute strings — use those instead of running Step 0.

Canonical documentation: skills/_shared/resolve-plans-dir.md.

SH-1. Input and issue number resolution: Input precedence (read whichever exists first): (a) <PLANS_DIR>/<session-id>-intent.md — preferred (post-clarify-intent calls) (b) <PLANS_DIR>/<session-id>-context.md — fallback (pre-clarify-intent calls from workflow-init) Issue number N:

• From intent.md: extract from ## Issues section (canonical parser: hooks/lib/parse-closes-issues.js).
• From context.md: read issue-number from ## Session metadata.
• If N is (none), absent, or non-integer → proceed in keyword-only mode (Step SH-3).

SH-2. Run: gh issue view <N> --json createdAt --jq .createdAt

• On success: record openedAt (ISO-8601 date string).
• On failure (gh unavailable, auth error, etc.): record "gh unavailable — using approximate date" and continue; set openedAt to 90 days ago as a conservative fallback.

SH-3. Keyword-only mode (no issue number available): Output header MUST include: **DEGRADED MODE** — no issue context; results are best-effort - Skip Step SH-2 (gh issue view) — no issue = no reliable issue data. - Skip gh pr list — no issue context means PR filter is unreliable. - Use --since='1 year ago' for git log scope (avoids unbounded history scan). - Source keywords from context.md ## Keywords section if present; otherwise extract from ## User initial prompt inline (≥4 chars, stop-words excluded). When initial keyword search returns zero results, extract 3–5 symptom-level tokens from ## User initial prompt or issue body text (behaviors, affected outputs/artifacts, feature area — including artifact/file names that represent the affected feature) and retry once. - Run Step SH-4a and SH-4b only (git log + history docs); skip Step SH-4c (gh pr list). - All claims produced in this mode get verdict: indeterminate (never holds or contradicted — insufficient evidence without issue context). - Rationale: without issue context, gh pr list has no filter; git log needs a date cap; verdicts require traceable evidence. After writing the artifact (Step SH-6), stop. Do NOT invoke make-outline-plan.

SH-4. Run the following three investigations in parallel:

a. Git log since issue opened: git log --since=<openedAt> --pretty=format:"%h %ad %s" --date=short

b. History docs entries since issue opened (follow progressive disclosure per skills/_shared/file-investigation.md): - Grep docs/history.md for date strings ≥ openedAt (format YYYY-MM-DD). Read the surrounding context (±5 lines) for each match. - If docs/history/index.md exists, grep it for the same date range to find archived entries. For each matching archive file listed in the index, read the relevant section of that file (e.g. docs/history/2025-*.md) to retrieve the full entry.

c. Merged PRs since issue opened: gh pr list --state merged --search "merged:>=<openedAt>" --limit 20 --json number,title,mergedAt On gh failure: record "gh pr list unavailable" and continue.

SH-5. Relevance scoring: Extract keywords from intent.md Background/Motivation and Scope (≥4 characters, excluding stop words: the, and, for, with, that, this, from, into, have, been). Score each commit/PR subject by keyword match count. Keep: score ≥ 1 entries, plus the top 5 by score regardless of threshold.

SH-6. Write <PLANS_DIR>/<session-id>-survey-history.md:

## Survey history — changes since issue #<N> opened (<openedAt>)

## Verified Claims
- claim: <text from intent.md Background/Scope>
  verdict: holds | contradicted | indeterminate
  evidence: <commit hash / PR# / history entry, or "no matching history found">

## Candidate class members
- <member name>: <one-line description> (from: <commit-ref or history entry>)
  proposed triage: <MUST | OPTIONAL | NA> — <one-line rationale>

## Premise impact assessment
<one paragraph: describe contradictions found, or state "No premise contradictions detected.">

The ## Candidate class members section lists sibling members identified from git history and history.md (per rules/core-principles.md CPR-4 Elevate Perspective). Each member is two lines: (a) name + description + commit/history-entry reference; (b) proposed triage: value and 1-line rationale grounded in historical evidence. Triage values: proposed triage: MUST (symmetric change required for class consistency), proposed triage: OPTIONAL (related but independently fixable), proposed triage: NA (orthogonal sibling, no fix needed). When uncertain, propose OPTIONAL. If no candidates are detected, write - (none detected). This section is required even in DEGRADED MODE or keyword-only mode.

If gh was unavailable, note it at the top of the file under a ## Data gaps section.

Rules

• Read project source files only — do not modify them. Writing the output artifact to <PLANS_DIR>/<session-id>-survey-history.md is required and allowed.
• Do NOT emit the research-complete sentinel — make-outline-plan MOP-0 aggregates both survey-code and survey-history before emitting it
• Do NOT emit premise-fail or premise-ack sentinels — these are emitted exclusively by the make-outline-plan orchestrator
• When invoked as a subagent, do NOT emit WORKFLOW_RESEARCH_NOT_NEEDED — the orchestrator handles it
• gh CLI failures are non-fatal: log them in the artifact and continue

Completion

Skip conditions

• closes_issues absent or empty and no context.md → emit WORKFLOW_RESEARCH_NOT_NEEDED
• No issue number available → use keyword-only mode (Step SH-3); do NOT skip entirely
• docs-only or typo task with no behavioral claims → emit echo "<<WORKFLOW_RESEARCH_NOT_NEEDED: docs-only task — history check not applicable>>"