SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgsd-path-inspect

gsd-path-inspect

Writing & research

View repository

Updated 10-16 07:25

About this skill

Before executing project helpers, read runtime selection and operating rules.

GSD Path Inspect Phase

Establish ground truth about an existing project before intent is defined. Detect, scan, and audit first; recommend and question only after the evidence is on disk. Never question a user about a codebase the pipeline has not read.

Routing instructions below are caller handoffs under the AGENTS.md handoff rule; never invoke an explicit-only sibling skill yourself.

Before phase work and again before completion, apply the AGENTS.md pending-answer rule with the bundled scripts/discussion_records.py; a follow-up owned by inspect is resolved through its artifact gate, or the phase blocks.

Preconditions

If STATE.md is missing, run the bundled python3 <absolute-bundled-script> initialize --repo <absolute-root> --template <absolute-state-template> --require-git helper (scripts/detect_project.py) and follow its returned JSON verdict / route. This is the only no-state boundary; do not run classify first or classify from a directory listing or conversation. Handle route: setup-repository before the write gate: preserve the folder unchanged and return to $gsd-path for repository setup; no state was written. If the command exits nonzero, returns error, or returns wrote_state: false, report the error and block without routing or claiming STATE.md was written.

  • owned — continue under the existing-state rules below.
  • orphan — return to $gsd-path for orphaned-state recovery instead of initializing or overwriting it.
  • greenfield — the helper writes STATE.md at define/active; skip inspection and route to $gsd-path-define from this returned verdict.
  • brownfield — require wrote_state: true, then continue with the helper's STATE.md at inspect/active. If .project/STATE.md exists, run python3 <absolute pipeline_state.py> validate --repo <absolute root> [--project-dir .project/next]; a non-zero result returns to $gsd-path for ownership checking. Legal entry is inspect/active|blocked; inspect/done routes to define, and any later phase stops. When an active router supplies .project/next/, require its STATE.md to be a regular non-symlink file and apply these rules to that track state. When an existing state records a bound branch (single-milestone restart or program next-milestone), require the current symbolic branch to match and preserve both branch and milestone. Do not re-enter inspect/done in the same milestone; a later milestone's inspect/active is a new scan.

Process

For an initial inspect/active inspection on the .project track, with neither output artifact present and a clean Git product at the recorded HEAD, run the bundled python3 <absolute workflow_run.py> prepare-inspect --repo <absolute root> --expected-head <recorded HEAD> first. It performs the inventory freeze and both sidecar preparations from steps 1–2 and writes complete assignment briefs. Its state validation and pending-answer check satisfy those entry checks; reuse their results at this boundary. Use its returned inspection.inventory_file for the gate. Before dispatch, read and apply the runtime dispatch contract, including its host-specific context isolation. Dispatch each returned logical task_name in a fresh context with its brief_file path and the current user constraints, including configured budgets. The child reads that file; the parent does not read or rewrite the roles, templates, or generated briefs. When both children return, review the mapper's Map and Findings against its template as in step 3. After that review passes, run the bundled python3 <absolute workflow_run.py> finish-inspect --repo <absolute root> --expected-head <recorded HEAD> --inspection <returned receipt_file> --mapper-reviewed. This runs the docs gate, checks the audit baseline, collects and retires both sidecars, checks pending discussion, and records inspect/done through the canonical transition. Do not repeat those operations. Present step 4's ground truth and use step 5's caller handoff. A failure uses step 3's failure contract and the returned step evidence; do not blindly rerun the completion command or repeat already proven steps. Prior evidence, lookahead, or a dirty/non-Git product uses steps 1–2 below. Preparation never changes phase state; neither command dispatches agents.

  1. Before creating or changing .project/ Markdown, freeze the helper's exact stdout from python3 <absolute check_docs_audit.py> --repo <absolute root> --emit-inventory in a temporary file. Do not rediscover or edit that inventory. If STATE.md is now missing, restart Preconditions and route from the new initialize result; never continue from an ignored result. Record the SHA-256 of each existing assigned destination and preserve the existing DOCS-AUDIT.md in a temporary prior-audit file; when it records an Audited HEAD Git resolves as an ancestor of HEAD, freeze the changed set as $gsd-path-docs-audit step 1 describes. Preserve an existing router-bound branch and milestone.
  2. Dispatch two independent agents in parallel, following the local runtime dispatch contract and its deterministic task-name rules:
    • Codebase mapper — role codebase-mapper, template codebase, output .project/research/evidence-codebase.md (.project/next/research/ in Lookahead mode), task name inspect_codebase.
    • Docs auditor — role docs-auditor, template docs-audit, output .project/research/DOCS-AUDIT.md (same next/ prefix in Lookahead mode), task name inspect_docs. Give each the absolute repo root and exclusion rule. Give the auditor the exact frozen inventory, the changed set when one exists, and alignment mode: false; it audits only that list and never rediscovers paths. The frozen inventory travels inside the dispatch brief; never persist it as a .project/ sidecar file. Pass an existing DOCS-AUDIT.md separately as carry-forward input so its ## User rulings and planned values remain verbatim. When Git has a resolvable HEAD and no non-.project worktree changes, the orchestrator creates a verify sidecar for each agent with python3 <absolute isolation.py> isolate-verify --repo <absolute primary> --base <HEAD> --name inspect-codebase and --name inspect-docs, and includes its path and revision for project commands; expected new pipeline artifacts do not make product code dirty. Each agent writes only its assigned output under that sidecar and keeps it there for the gates in step 3; its Repo root header still names the absolute primary. Otherwise no project command may run. The docs-auditor brief carries current HEAD as the audit baseline only when its verify sidecar was created at HEAD; otherwise it carries none. The auditor writes that baseline as Audited HEAD.
  3. Gate both artifacts against their templates: the codebase evidence needs a filled ## Map plus findings as observed — no quota, but an empty findings section must say why; the docs audit must pass the bundled python3 <absolute check_docs_audit.py> --repo <docs sidecar> --primary <absolute primary> --audit <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>, where the audit path is .project/research/DOCS-AUDIT.md normally and .project/next/research/DOCS-AUDIT.md in Lookahead mode; add --prior-audit <temporary prior-audit file> when one was preserved and --changed <temporary changed-set file> when one was frozen (disjoint ## Doc: sections and ## Descriptive docs equal to the frozen inventory, every claim a valid verdict with evidence, Summary counts and remediation queue consistent). After each artifact passes, collect it with python3 <absolute isolation.py> collect-artifact --repo <absolute primary> --source <returned worktree> --base <recorded HEAD> --branch <returned branch> --source-path <assigned track-relative path> --destination-path <assigned track-relative path>, adding --expected-destination <recorded prior SHA-256> when that destination existed. Require the returned base, branch, source, and destination to match. Only then retire with python3 <absolute isolation.py> retire --repo <absolute primary> --worktree <returned worktree> --branch <returned branch> without --force. Redispatch one complete corrected brief under the same logical task name, following the runtime dispatch contract. If it still fails, run pipeline_state.py transition with expected inspect/active, the exact current branch and archive values, --set-status blocked, and an event naming the failed artifact gate. Present Outcome with the failed gate, Review linking each malformed output that exists or STATE.md when an output is missing, and Next naming the one correction or user decision required; then stop.
  4. Present the ground truth to the user, brief — a summary, not a dump:
    • what the project is (stack, architecture, entry points, maturity);
    • what demonstrably works (verified claims, passing verifies);
    • drift: what the docs claim that the code contradicts, and what exists with no documentation at all;
    • the mapper's open questions about apparent intent. Lead with the outcome, then provide absolute-path Markdown links to the track's research/evidence-codebase.md and research/DOCS-AUDIT.md (.project/research/ normally, .project/next/research/ in Lookahead mode), then state that define is next.
  5. Run python3 <absolute pipeline_state.py> transition --repo <absolute root> [--project-dir .project/next] --event "inspection artifacts passed" --expect-phase inspect --expect-status active --expect-milestone <current milestone or null> --expect-branch <current branch or null> --expect-archive <current archive or null> --set-phase inspect --set-status done. This helper is the only ordinary STATE mutation; require its returned state to be inspect/done. Use the executable phase handoff in AGENTS.md.

Lookahead mode

Entered only when an active router supplies the lookahead track root .project/next/ while the active STATE.md is build/active in program flow. Evaluate every state and artifact precondition against the track: .project/next/STATE.md is the state file and the outputs are .project/next/research/evidence-codebase.md and .project/next/research/DOCS-AUDIT.md. Freeze the inventory from the repository root as usual. Carry forward the active .project/research/DOCS-AUDIT.md when it exists so its ## User rulings and planned values remain verbatim; otherwise carry forward a track-local audit if present. Never write an active-path artifact.

Rules

  • Scanning is read-only. Inspection changes nothing outside .project/.
  • Project commands run only in agent-specific disposable verification worktrees at a recorded clean revision; otherwise checks use static evidence or are unverifiable. They never run in the source worktree.
  • Report reality, not judgment: "tests exist but 3 fail" — never "test hygiene is poor". The user may know exactly why those 3 fail.
  • Doc-vs-code conflicts are surfaced, never auto-resolved; whether the doc or the code is wrong is the user's ruling, captured while defining intent.
  • Inspection evidence feeds the whole pipeline: researchers treat evidence-codebase.md as a fifth standard dimension when it exists, the planner must match its conventions, and reviewers may cite it.