forge-clarify

Forge Clarify

This is the step between triage and plan: confirmed → clarified. Its job is to validate understanding — reproduce bugs in a live environment, verify UX expectations for features, and capture visual evidence. This prevents the plan step from targeting the wrong code path or misunderstanding the desired outcome.

Every issue passes through clarify — there is no auto-skip. Scale the depth to the issue: a trivial xs/s change needs only a quick intent restate + confidence check (no full reproduction), while a bug or larger feature gets the full investigation below.

Usage

/forge-clarify <documentId>

Tools

• forge_issues — get/update issues
• forge_comments — list/create comments
• Browser (optional) — if a browser-automation MCP is available, use whatever browser tools the runner exposes (auto-detected; usually surfaced as browser_*: navigate, click, type, snapshot/screenshot). Do not hardcode a provider. If no browser MCP is available, fall back to curl/WebFetch HTML checks.
• WebFetch — for API endpoint testing

Workflow

Pull-model note: On large issues forge_step_start returns a lean manifest (bodyTruncated:true). Fetch description/acceptanceCriteria as needed via forge_issues.get { documentId, fields: ['description', 'acceptanceCriteria'] } rather than assuming full body is present.

Step 1: Fetch Issue & Triage Context

Fetch the issue and its comments in parallel:

forge_issues → get → { documentId: "<id>" }
forge_comments → list → { filters: { issue: "<documentId>" } }

Find the triage comment (starts with **Triage** by Snorlax) and extract complexity (xs/s/m/l/xl) and category — they set how deep to go (trivial → quick restate; bug/large → full investigation).

Step 2: Resolve Live Environment

Determine where to test:

1. Project's staging URLs from forge_config → get (previewDeploy.stagingUrl / stagingApiUrl)
2. If none available → skip browser testing, note in comment