ag-feasibility-test

Files (5)

• SKILL.md
• fail.md · scripts/fixtures/validate-feasibility-verdict/
• pass-pvl.md · scripts/fixtures/validate-feasibility-verdict/
• pass.md · scripts/fixtures/validate-feasibility-verdict/
• validate-feasibility-verdict.mjs · scripts/

SKILL.md (first lines)

# ag-feasibility-test

## When to Apply

Use this skill when working with ag-feasibility-test workflows, tasks, or system specifications.

## How to Use

Refer to the workflow instructions and command references detailed below.

> **Output style:** Follow `process/development-protocols/communication-standards.md` — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

One-shot empirical probe skill. Used when SPEC or INNOVATE encounters an approach
hinging on an unverified external/runtime/library mechanism — the question is
**"does this mechanism actually work the way the design assumes?"**, asked
**before** the decision locks.

## Boundary vs ag-test-coverage-plan

These two skills are complementary and must not be confused:

- **`ag-feasibility-test` (this skill) = PRE-decision.** "Does the mechanism work at
  all?" Run _before_ SPEC/INNOVATE locks an approach, when the answer is unknown.
  Output: a one-shot VERDICT artifact.
- **`ag-test-coverage-plan` = POST-plan.** "How do I cover this blast radius across
  the 4 test tiers?" Run _after_ a plan exists, when the design is already chosen.
  Output: a per-area tier table.

If the approach is already decided and you are assigning test tiers → use
`ag-test-coverage-plan`. If you cannot decide _because_ a mechanism is unverified →
use this skill first.

## When To Invoke

- When ag-spec-agent, ag-innovate-agent, or a ag-validate-agent Layer 2 dimension agent emits `VC-FEASIBILITY-PROBE-NEEDED`
- When a mechanism cannot be verified from source code alone
- One-shot: not an iterative loop (use ag-autoresearch for iteration)

## Skill Executor

Always executed by ag-debugger (via the `VC-FEASIBILITY-PROBE-NEEDED` signal routing
in orchestration.md). SPEC, INNOVATE, and VALIDATE Layer 2 agents do not run probes themselves.

## Probe-Method Taxonomy (pick one family)

Every probe belongs to one of these 8 families. Name the chosen family in the VERDICT.
Each family has a default cost/safety class (see next section) — the probe inherits it.

| #   | Family                                  | What it probes                                                           | Typical method                                                             | Default cost class                                                      |
| --- | --------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| 1   | **Local process / Node script**         | pure library/runtime behavior in isolation                               | run a `.mjs`/Bun script, regex/parse check, call the lib fn directly       | cheap-local                                                             |
| 2   | **Unit/integration test harness**       | behavior under the project's own test runner                             | `pnpm --filter … test` (Vitest) or `bun test` on a scratch case            | cheap-local                                                             |
| 3   | **tRPC / Prisma / DB query**            | route shape, query behavior, index/constraint semantics                  | hit a tRPC route or run a Prisma/raw-SQL query against a test DB           | needs-container _(only if it needs the live app DB)_ / else cheap-local |
| 4   | **External API shape capture**          | real response shape/behavior of a 3rd-party API                          | one live request to OpenRouter / Stripe / Composio / Clerk / Bright Data   | **needs-live-provider**                                                 |
| 5   | **Container exec / internal-port curl** | in-container service behavior, proxy injection, file-server, supervisord | `docker exec … curl http://localhost:{port}` on a **disposable** container | **needs-container**                                                     |
| 6   | **Browser / CDP capture**               | anti-detect quirks, CDP events, SPA nav, popup behavior                  | Playwright/CDP client, `page.on(...)`, snapshot                            | needs-browser                                                           |
| 7   | **WS / SSE handshake & timing**         | gateway WS framing, SSE delivery/reconnect, JSONL shape                  | raw `ws`/`EventSource` client + frame/timing capture                       | needs-container _(if against in-container service)_ / else cheap-local  |
| 8   | **Cloudflare worker runtime**           | KV staleness, step-replay/idempotency, edge JWT verify                   | `wrangler dev` + curl, deploy a throwaway worker                           | needs-cf                                                                |

If none of the 8 fit, the question is probably not a feasibility probe — reconsider
whether `ag-research-agent` (unknown _context_) or `ag-test-coverage-plan` (known
design) is the right tool instead.

## Probe Cost / Safety Class (MANDATORY GATE)

Every VERDICT declares one cost class. The class governs whether the probe may run
unattended or needs explicit opt-in. **A probe that cannot be run within its safety
gate produces an `INCONCLUSIVE` verdict — it is never silently skipped or faked.**

| Cost class              | Safety gate                                                                                                                                                                                  | If gate not met                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **cheap-local**         | none — run freely (local script, test harness, parse check)                                                                                                                                  | n/a                                                              |
| **needs-container**     | use a **disposable** container only. NEVER `docker exec` the shared dev container (`app-*`) or shared Postgres. Disposable live-E2E containers need the disposable-cleanup env gate enabled. | verdict `INCONCLUSIVE`, note "no disposable container available" |
| **needs-live-provider** | requires explicit **double opt-in** from the user before any billed/live 3rd-party call (OpenRouter, Stripe, Composio, Bright Data, Clerk). Default local mode is BYOK Mistral.              | verdict `INCONCLUSIVE`, note "live-provider opt-in not granted"  |
| **needs-browser**       | a browser/CDP session must be available; never drive a shared user session                                                                                                                   | verdict `INCONCLUSIVE`, note "no browser session available"      |
| **needs-cf**            | a `wrangler dev`/throwaway-worker sandbox; never touch a deployed production worker                                                                                                          | verdict `INCONCLUSIVE`, note "no CF sandbox available"           |

The emitted `VC-FEASIBILITY-PROBE-NEEDED` signal SHOULD carry the anticipated cost
class so the orchestrator can resolve the opt-in gate before dispatching ag-debugger
(see orchestration.md §VC-FEASIBILITY-PROBE-NEEDED Signal Routing).

## Probe Execution Steps

1. Read the hypothesis from the `VC-FEASIBILITY-PROBE-NEEDED` signal
2. Pick the probe **family** (1–8) and its **cost class**
3. Confirm the safety gate for that cost class is met. If not → write an
   `INCONCLUSIVE` verdict with the gate-not-met reason and stop. Do NOT escalate
   to a higher-cost probe or run against a shared resource.
4. Design the minimal probe within that family
5. Run the probe empirically — capture actual output, not expected output
6. Analyze the evidence: does it confirm or refute the hypothesis?
7. Assign a verdict: `VIABLE` | `NOT-VIABLE` | `INCONCLUSIVE`
8. Write the VERDICT artifact to the active task folder

## VERDICT Artifact Format

Filename: `{slug}_FEASIBILITY_{dd-mm-yy}.md`
Location: same active task folder as the SPEC/plan that triggered the probe

**Required frontmatter fields (MUST be present — validated by `validate-feasibility-verdict.mjs`):**

```yaml
---
slug: [task-slug]
date: YYYY-MM-DD
verdict: VIABLE | NOT-VIABLE | INCONCLUSIVE
originating-phase: spec | innovate | pvl
---
```

The `originating-phase:` field is REQUIRED. Valid values:

- `spec` — probe triggered by ag-spec-agent ([SP3])
- `innovate` — probe triggered by ag-innovate-agent ([I2.5])
- `pvl` — probe triggered by ag-validate-agent Layer 2 ([V2-PROBE])

Required sections (MUST be present — validated by `validate-feasibility-verdict.mjs`):

### Hypothesis

From ngxccc/agent-skills-kit, MIT.

More from ngxccc/agent-skills-kit