skillscope-analyzer

SkillScope Analyzer

Purpose

Analyze the selected skill-use window only. Current chat or whole-machine history is out of scope unless an input file explicitly points to it.

SkillScope provides file paths for the selected skill, normalized skill units, normalized trace events, raw trace text, and output artifacts. Follow those files, not assumptions.

Required Workflow

1. Read all paths named in the launch prompt.
2. Read the selected SKILL.md and the normalized skill units.
3. Compile the skill into analysis IR: constraints, condition predicates, obligations, prohibitions, ordering rules, and output contracts.
4. Start from constraint-seed.json when present; review and refine it instead of re-deriving every line from scratch.
5. Write or update constraints.json as soon as the constraint review is complete.
6. Write or update skill-graph.json after extracting constraints and before judging the full trace.
7. Compile the trace into trace-facts.json: event facts, artifact facts, ordering facts, and final-output facts.
8. Read native-verifier.json when the launch prompt provides it. Treat it as deterministic evidence for final-output/artifact contracts only.
9. Run path-sensitive coverage over the skill graph using trace facts plus native verifier facts.
10. Update graph branch/path state after trace inspection.
11. Append concise progress notes to progress.md after each meaningful stage.
12. Write findings.json when you have coverage judgments worth surfacing.
13. Keep this pass focused on analysis artifacts; SkillScope launches skillscope-optimizer after findings.json is saved.
14. Finish with a human-readable report citing evidence event IDs and native verifier facts where used.

Program Analysis Model

Treat the selected SKILL.md as a small specification program and the selected trajectory as one execution trace of that program.

Use this compiler-style analysis pipeline:

1. Skill front-end
   • Parse Markdown headings as modules / basic blocks.
   • Parse bullets, numbered items, tables, examples, and output schemas into fine-grained constraints.
   • Classify constraints into condition, obligation, prohibition, ordering, numeric_bound, command_contract, file_contract, evidence_requirement, and final_output_contract.
   • Also classify each constraint target as final_output, artifact, process, tool_use, reporting, or unknown.
   • Classify whether each constraint is a hard contract, soft recommendation, or implementation hint. Treat illustrative/reference code internals as hints unless surrounding prose says they are mandatory.
   • Keep precise source spans. If one sentence contains two obligations or an obligation plus a condition, split it.