predict

Files (1)

• SKILL.md

SKILL.md (first lines)

# `predict` — Pre-Implementation Multi-Persona Analysis

Structured pre-implementation review. Five expert personas assess the proposal
**independently**, then debate, then converge on a verdict with a confidence
score. Surfacing architectural, security, performance, and UX flaws before the
first commit is the cheapest place to catch them.

---

## When to invoke

Use before implementing any of:
- A new transport strategy (`sapisidhash`, `cdp_attach`, `official_veo`)
- Auth flow changes (new strategy, G12 bypass technique, cookie extraction)
- Selector cascade redesigns affecting `ONBOARDING_SELECTORS`, `NEW_PROJECT_SELECTORS`, `FRAME_SLOTS_STRUCT`
- Schema migrations in `gflow_cli/data/`
- New CLI surface or exit-code changes
- Any backlog item with an "investigation gate" in PLAN.md before coding

Skip for: trivial bug fixes (< 10 lines, isolated, no boundary cross), already-approved PLAN.md tasks entering EXECUTE, pure doc changes.

---

## Invocation

```
/gflow:predict <proposal>
```

`<proposal>` is a short description of what you intend to build or change —
one paragraph is enough. Examples:
- "Wire SAPISIDHASH auth header into `_post_json` for all `aisandbox-pa` routes (Issue #15)"
- "Add CDP-attach transport as opt-in `--transport cdp_attach` alongside `ui_automation`"
- "Redesign `gflow video batch` to use a local manifest ledger for skip-already-done"
- "Add `AuthBrowserBlockedError` to `internal_chromium.py` when Google rejects bundled Chromium"

---

## Protocol

### Phase 1 — Persona briefings (parallel)

Dispatch five personas simultaneously. Each reads `AGENTS.md`, `PLAN.md`, `KNOWN_ISSUES.md`, and the relevant source files for the proposal. Each assesses **independently** — no persona sees another's output during Phase 1.

#### Persona 1 — Architect
*Scope: hexagonal target, modular-monolith current shape, dependency direction, module boundary rules.*

Asks:
- Does this proposal respect the dependency rule (`interfaces → application → domain ← infrastructure`)?
- Which module does this live in? Does it fit cleanly or does it need a new module, and if so, is that justified?
- Will this make the eventual DDD graduation harder or easier?
- Are there hidden coupling risks (e.g., a transport leaking into `cli.py`, a domain model importing from `infrastructure`)?
- Does the proposed shape match the existing pattern (Protocol-based ports, frozen dataclasses for value objects, `structlog` for all logging)?

Output: structured analysis, confidence `0–10`, architectural risks.

#### Persona 2 — Security / reCAPTCHA
*Scope: Google's anti-bot stack, SAPISIDHASH, G12 block, WAF scoring, profile isolation, secret storage.*

Asks:
- Does this touch auth headers, cookie extraction, or token minting? If yes, what's the trust boundary?
- Could this trigger WAF score inflation on a per-profile basis?
- Does the Chrome profile isolation guarantee (`SecurityError` if profile_dir outside `GFLOW_CLI_HOME`) remain intact?
- Are any auth secrets (SAPISID, bearer tokens, reCAPTCHA tokens) at risk of leaking to logs? (`show_locals=False` is mandatory on exception renderers.)
- Could this bypass the G12 stealth flag mechanism or reintroduce `navigator.webdriver=true`?
- What's the attack surface against a third party who controls the Flow UI (XSS / selector injection)?

Output: structured analysis, confidence `0–10`, security risks with severity.

#### Persona 3 — Performance / Playwright
*Scope: Page pool, `asyncio.gather`, reCAPTCHA mint latency, headless detection, BrowserContext lifecycle.*

Asks:
- Does this add latency to the hot path (per-generation or per-poll)?
- Does it interact with the Page pool (`_checkout_page` / `_checkin_page`)? Is there a `QueueFull` risk?
- Does it require additional `page.evaluate` calls? What's the latency budget vs the 200 ms/page threshold?
- Does it affect `GFLOW_CLI_CONCURRENCY`? Could it reduce or increase the safe ceiling?
- Could running this in a headless context trigger reCAPTCHA detection or WAF scoring?
- Does it add any persistent state that's not cleaned up when `FlowApiClient.__aexit__` runs?

Output: structured analysis, confidence `0–10`, performance bottlenecks.

#### Persona 4 — CLI **and MCP** UX / Cross-platform
*Scope: exit codes (RFC 9457), `structlog` events, Windows/macOS/Linux path handling, `--help` text, error recovery UX, **and the MCP tool surface that mirrors all of it**.*

Asks:
- **Does this change land on the MCP surface too, and what breaks if it does not?** gflow ships every capability twice — as a CLI command and an MCP tool — and the automated parity gate is command-level only, so an unmirrored option or a docstring that still describes removed behaviour passes every check. Name the affected MCP tool, the payload keys on the queued `worker/codec.py` path, and any docstring claim that becomes false. If the proposal genuinely has no MCP surface, say so explicitly — silence here is what let #626 ship a CLI unlock with `mcp/tools.py` still telling agents the combination was rejected.
- What exit code does failure produce? Is it in `EXIT_CODE_MAP`? Is it distinct from existing codes?
- What `structlog` events does this introduce? Are `error_raised` / `error_unhandled` paths handled?
- Are new env vars or flags introduced? Do they follow `GFLOW_CLI_*` convention and have a `.env.template` entry?
- Does the UX degrade gracefully if the new feature fails (remediation hint in error message)?
- On Windows: are path separators, `platformdirs` paths, and `PYTHONUTF8=1` requirements respected?
- If this is a new subcommand or flag: is the `--help` text self-contained and accurate?
- Does this change touch DOM selectors? If yes, are selectors strictly locale-invariant (Tier 1 structural/ARIA/icon/href anchors + Tier 2 multi-locale text cascades across EN, PT, ES, DE, FR, IT, JA, ZH, KO), rejecting single-language English-only selectors?

Output: structured analysis, confidence `0–10`, UX friction points.

#### Persona 5 — Devil's Advocate
*Scope: YAGNI, simpler paths, interaction with KNOWN_ISSUES, backlog sequencing.*

Asks:
- Is there a simpler way to achieve the same user outcome (fewer files, less Playwright surface, existing code reuse)?
- Does PLAN.md already have an ADR that contradicts or defers this work?
- Is there a known issue in `KNOWN_ISSUES.md` that makes this approach risky or likely to fail?
- If this fails in production (WAF score spike, reCAPTCHA regression, selector drift), what's the rollback story?
- Is the timing right? Does something else need to land first (e.g., Issue #14 before Issue #15)?
- What's the simplest experiment (smoke test, `scripts/` script, isolated spike) that could prove/disprove the core assumption before committing to a full implementation?

Output: structured analysis, confidence `0–10`, alternative paths, blocking concerns.

---

### Phase 2 — Conflict resolution

After all five personas return:

1. **Tally signals.** Identify any dimension where 2+ personas flag the same concern — those surface as high-confidence risks.
2. **Resolve conflicts.** If Architect says "fits cleanly" but Devil's Advocate says "ADR #13 defers this" — surface the conflict explicitly. Do NOT silently suppress one view.
3. **Score overall confidence** as the average of the five persona confidence scores, then apply modifiers:

From ffroliva/gflow-cli, MIT.

More from ffroliva/gflow-cli