Analysis Core

Analysis Core

Internal shared skill. Single source of truth for analysis-stage methodology used by PDCA fix workflows. Workflows keep their own orchestration (exits, manual/auto mode, OpenSpec/Jira artifact sinks, intentional divergences).

Prerequisite check: this skill declares strong dependencies in frontmatter. On load, verify each is available; if any is missing, abort and print the install command (npx skills add FuDesign2008/open-skills -g --skill '*' --yes). No silent fallback.

Placeholder contracts

This skill is shared by workflows with different stage numbering. Never hardcode a workflow's stage numbers or titles here.

1. Temporary-change permission and rollback gate

Analysis is read-only by default. Analysis-assist edits only are allowed; they must be registered and fully rolled back before entering {next-stage}. Fix implementation belongs in the workflow's execution stage — not here.

Allowed (analysis-assist only):

• Instrumentation, temporary logs, reproduction scripts
• Hypothesis-validation edits (e.g. flip a condition to observe behavior) — restore after validation

Forbidden: edits whose purpose is to implement the fix.

Register (mandatory): for every temporary edit, record immediately: file + location + original content + purpose (rollback basis).

Exit gate (must complete before {next-stage}):

1. Restore originals one-by-one from the register (register is authoritative; git diff only helps confirm register items are clear — the worktree may already have user edits)
2. Output「临时改动清单 + 回滚验证」
3. If anything remains unrolled-back, do not enter {next-stage}; keeping an edit requires explicit user confirmation
4. Close the stage output with the §5 analysis gate output block (its temporary-changes line carries this list)

Tool limits (analysis stage): ✅ Read/Grep/SemanticSearch; ✅ WebSearch (research routing / quick search / upstream-eval / runtime-evidence-debug escape hatch); ✅ Edit/Write only for analysis-assist edits above; ✅ Bash for read-only verification commands — running the app under debug or reproduction steps still needs user confirmation (see §3).

2. Analysis step skeleton

1. Existence check (gate — always first)

   • Locate relevant code with Read/Grep/SemanticSearch
   • Act on the verdict:

   Verdict	Action
   ✅ Problem exists	Continue to step 2 → 3–8
   ❌ Problem gone	Report it may already be fixed or logic changed, cite locations, stop and wait for user
   ⚠️ Description mismatches code	Report the mismatch, return to the workflow's problem-clarification stage

2. Research routing — load known-issue-research and follow it (triage + known-issue quick search + industry-wide evaluation). The referencing workflow's reference line supplies {root-cause step} / {impact-assessment step} / {upstream-eval step} maps. Report templates: known-issue-research/reference.md.

3. Phenomenon — reproduction conditions/steps; when the issue is browser-reproducible, prefer browser-debug-toolkit to reproduce and observe runtime state (not limited to UI/CSS/DOM; follow that skill's degradation path if browser automation is unavailable).

4. Locate — file paths + line numbers, key functions/classes.

5. Red-capable loop gate (before multi-hypothesis root-cause guessing)

   • A red-capable loop = a deterministic, agent-runnable failing reproduction (command, test, or equivalent observed failure) that has already been run at least once in this analysis stage and observed red/failing.
   • A user-reported symptom (pasted log, verbal description, screenshot) does not count as an agent-observed red.
   • If missing: do not emit a speculative multi-hypothesis “likely root causes” list. First establish the loop (repro steps, instrumentation per §3). If no agent-runnable loop can be established, the escape MUST land as an explicit user handoff — instrumentation and reproduction steps handed to the user per runtime-evidence-debug's human-AI division — or a stop with the gap stated; never a silent pass.
   • If present: proceed to step 6. The stage output closes with the §5 analysis gate output block (red-loop line included).

6. Root cause — data flow and call-chain analysis; falsifiable hypotheses only after step 5 is satisfied.

7. Upstream dependency fix evaluation (optional) — when root cause is an upstream dependency bug, or step 2 found an upstream fixed version: load upstream-dependency-debug and follow it. Outcomes: low-risk upgrade → recommend upgrade in solution exploration; risky → list upgrade alongside workarounds; unfixed → workaround marked temporary.

8. Impact — affected modules/features.

If existence fails or description mismatches, do not proceed to solution exploration.

Analysis-stage red flags

• Research route is 🔵/🟣 but known-issue quick search is skipped; or 🟢 with quick-search triggers hit yet WebSearch is skipped for “read code first”
• Named third-party lib/framework in the root cause without checking upstream Changelog/Release Notes before piling workarounds
• Using “analysis” to ship a fix — temporary edits beyond hypothesis validation, or entering {next-stage} without rollback
• Temporary edits not registered, or missing「临时改动清单 + 回滚验证」before {next-stage}
• Emitting multi-hypothesis root-cause guesses without a red-capable loop (or an explicit, user-visible statement that no loop is possible)

3. Instrumentation debug (runtime observation — default entry)

State-based triggers (any one; prefer before entering {next-stage}):

• Static analysis stalled — module roughly known, concrete mechanism or path unconfirmable by reading code
• Retry/continue — a fix based on static analysis was applied and the problem remains
• Silent failure — call chain and logs look correct but behavior is wrong
• Fix verification needs before/after runtime evidence

Default entry: when any trigger fires, load runtime-evidence-debug first and follow its lifecycle (escalation decision → instrumentation design → reproduction → evidence tiers → confidence gating → escape hatch → fix verification). Entry is a state judgment ("runtime observation is needed"), not a self-assessed confidence verdict; the skill's own static-first escalation decision remains authoritative.

Scenario composition (on demand; each keeps its own authority):

• Browser-reproducible → instrumentation delegates tool selection to browser-debug-toolkit; if the phenomenon step already did browser repro, continue here only if static analysis still stalls
• Hybrid app (native shell + WebView/WKWebView/Electron + H5) → consult hybrid-debug for layer localization before instrumenting
• Real-device observation → compose channel enablers (e.g. android-webview-debug to establish the connection); runtime-evidence-debug decides what to observe, evidence tier, and when confidence suffices

Execution details, confidence gating, and escape hatches live in each skill's current SKILL.md — read before invoking.

Tool limits: ✅ Read/Grep to choose instrumentation sites; instrumentation and validation edits follow §1 (AI may add instrumentation and must register it); ❌ do not run reproduction steps without user confirmation.

4. Debug-verify loop (verification stage)

When the analysis stage used a debug skill to find the root cause, the workflow's verification stage MUST use the same skill to verify the fix (not tests alone):

• Browser-reproducible (browser-debug-toolkit) → same skill; before/after runtime state (DOM / computed style / box model / console / network); confirm the anomaly is gone
• Runtime evidence (runtime-evidence-debug) → re-check original instrumentation sites; before/after evidence; confirm abnormal behavior is gone
• Hybrid (hybrid-debug) → verify affected layers (L1–L4); no new cross-layer side effects

5. Analysis gate output block (mandatory stage-closing block)

Single source of truth for the block that MUST close every referencing workflow's analysis-stage output before entering {next-stage}. Workflows reference this block with a thin pointer; they never restate its fields.

【Analysis gate / 分析门控】
Red loop: ✅ <command + one-line red evidence observed this stage> / ❌ <why unestablished + handoff already proposed: instrumentation/repro steps handed to the user>
Debug entry: runtime-evidence-debug loaded (trigger: static stalled / retry / silent failure / before-after verification) / not needed (one-line Tier 1–2 evidence)
Scenario supplements: browser-debug-toolkit / hybrid-debug / channel enabler (e.g. android-webview-debug): engaged(<which>) / not needed
Temporary changes: none / <registered list + rollback verified>

Rules:

• A missing or unfilled block blocks entry to {next-stage} — filling it is the entry condition, and being unable to fill a line (e.g. red loop) is itself the escalation signal.
• "Not needed" fills are legal but require their one-line evidence; blank or evasive fills are not.
• Red-loop line follows §2 step 5 (user-pasted evidence does not satisfy it); debug-entry line follows §3 (state-based trigger).

Integration guide (for referencing workflows)

• Declare analysis-core in frontmatter dependencies; abort at workflow startup if missing.
• Thin reference shape (preferred): one short「委托 analysis-core」block with {next-stage} + known-issue-research step maps (number + name only); do not restate §§1–3 prose or re-list the analysis step skeleton.
• Keep in the workflow body: orchestration only — exits/mode, OpenSpec/Jira sinks, intentional divergences (形似神异), difficulty/path tables.
• Verify stage: one line pointing at §4 — do not paste debug-verify bullets.
• reference.md: point to this skill for methodology; keep workflow-specific output templates; do not duplicate gate prose.
• Do not sink intentional divergences (coverage-gate strength, test-suite-ensure blocking, industry-eval Jira gate, etc.) into this skill.