/context

user-invocable: false
description: Pre-implementation context gathering — surfaces historical findings, bug patterns, and related code paths before the builder writes any code
argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE} --files \"<space-separated>\" [--functions \"<names>\"]"
context: fork
background: false

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

work-on/build/context — Pre-Implementation Context Gathering

**Invoked by**: `work-on:build` (phase B3), between Builder Contract and Architect, via `Skill()`. Runs in its own forked context: you see only this spec and your args — re-read all other state from GitHub/git. **Time budget**: Max 2 minutes of queries. Skip any query that times out. **Output**: Post `<!-- FORGE:CONTEXT -->` comment on the issue, then print exactly one `CONTEXT_RESULT:` block (see Result Block) as your final reply. Every exit path — success, partial, skip, failure — prints it.

<!-- FORGE:SPEC_LOADED — work-on/build/context.md loaded and active. Agent is bound by this spec. -->

---

COMPLEXITY_BAND Guard (check BEFORE all phases)

Read COMPLEXITY_BAND from the `<!-- FORGE:FAST_PATH -->` comment on the issue:

COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
  --jq '.[] | select(.body | contains("FORGE:FAST_PATH")) | .body' 2>/dev/null \
  | sed -n 's/.*\*\*COMPLEXITY_BAND\*\*: \([A-Z_]*\).*/\1/p' | head -1)
COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"

**If COMPLEXITY_BAND: TRIVIAL or INVESTIGATION** → skip all phases (C-1 through C4), post NO comment, print `CONTEXT_RESULT:` with `status: SKIPPED` and `comment_url:` empty immediately. Do not query GitHub, do not read files. This is not an error — trivial single-file changes (and investigation tasks, which produce issues rather than code) have no institutional memory to surface. <!-- Added: forge#679 -->

**If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase C-1 below.

---

Mission

Surface what went wrong in this area before the builder writes a single line of code. The builder starts with the investigator report and contract — this step adds institutional memory: what did review agents catch last time someone touched these files, what bugs recurred, what other paths must stay consistent. When prior investigation Gists are linked in the issue body, fetch and summarize them so the builder has cross-issue context without manual lookups. When a milestone-level index Gist exists, use it to discover all investigation Gists for the milestone — providing full cross-issue context from a single URL. <!-- Updated: forge#341 -->

**Principle**: A builder with context produces fewer review findings. Fewer findings = fewer fix cycles = lower token cost.

---

Inputs

Parse from `$ARGUMENTS`:

• `{NUMBER}` — issue number (positional, required)
• `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
• `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
• `--repo-path {REPO_PATH}` — local filesystem path to the worktree (e.g. `/path/to/.claude/worktrees/fix/issue-121`); used by Phase C3 grep commands
• `--files "{AFFECTED_FILES}"` — space-separated file paths (quoted as one value; an empty value is allowed and triggers the empty-list skip)
• `--functions "{FUNCTION_NAMES}"` — space-separated function/class names extracted from the Builder Contract deliverables table (optional)

**Fail closed**: if `{NUMBER}`, `--repo`, `--gh-flag` or `--repo-path` is missing, print `CONTEXT_RESULT:` with `status: SKIPPED` and `comment_url:` empty plus a one-line `note: missing arg <name>` and stop (context is advisory — a missing arg must never block the build, but it must be visible).

**Graceful skip for empty FUNCTION_NAMES**: If `--functions` is absent or `{FUNCTION_NAMES}` is empty, Phase C3 produces zero for-loop iterations and is effectively skipped — no error, no output for that phase. This is expected behavior when the contract does not name specific functions.

---

Phase C-1: Authoritative Devdocs

Read project-resident authoritative docs **before** any institutional-memory queries. Devdocs contain binding project knowledge (conventions, architecture, custom instructions) that must inform the builder's mental model from the start.

**Time budget**: 30 seconds. If exceeded, log a skip note and continue to Phase C0.

**Skip if**: `{REPO_PATH}` is not set, devdocs path does not exist, or path contains no markdown files.

Step 0: Resolve devdocs path

Read `forge.yaml → devdocs.path` from the project root. Default to `devdocs` if the key is absent or unreadable.

DEVDOCS_PATH=""

# Read forge.yaml directly from repo root (REPO_PATH points to the project root — no directory walk)
FORGE_YAML_PATH="{REPO_PATH}/forge.yaml"

if [ -f "$FORGE_YAML_PATH" ]; then
  # Extract devdocs.path key (simple grep — value is on the same or next line under "devdocs:")
  DEVDOCS_REL=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
    | grep '^\s*path:' \
    | head -1 \
    | sed 's/.*path:\s*//' \
    | tr -d '"'"'"' \
    | tr -d '[:space:]')
fi

# Default to "devdocs" if not found
DEVDOCS_REL="${DEVDOCS_REL:-devdocs}"
DEVDOCS_PATH="{REPO_PATH}/${DEVDOCS_REL}"

if [ ! -d "$DEVDOCS_PATH" ]; then
  echo "Devdocs path '${DEVDOCS_PATH}' does not exist — skipping Phase C-1 (no blocking)"
  DEVDOCS_PATH=""
fi

> **Note**: `devdocs/` must be tracked in git for the worktree to contain it. If the project gitignores `devdocs/`, the path will not exist in the worktree and this phase silently skips — this is by design. Run `git check-ignore -v devdocs/` to confirm tracking status.

Step 1: Enumerate and filter applicable files

**Index-first path** (preferred when `index.yaml` exists): Read the lightweight index, extract issue labels to filter by domain, load only matching docs. Falls back to O(N) enumerate when index