analyze-with-file

What it does

Translates a given topic into an organized, step-by-step collaborative analysis workflow that records discussion history, decisions, and findings. It performs topic understanding, inline exploration of the codebase, multi-round discussions, synthesis, and optional plan generation. It supports up to 4 analysis perspectives and ensures every critical decision and finding is documented in a structured format. It uses a specific command set and file structure to manage sessions and artifacts.

How it works

• Initializes a session from a topic, parsing flags for depth, continuation, and auto-confirm; generates a session ID of the form ANL-{slug}-{YYYY-MM-DD} and creates a session folder.
• Step 1: Topic Understanding
  • Identifies analysis dimensions by matching topic keywords to predefined categories (architecture, implementation, performance, security, concept, comparison, decision).
  • If not continuing, prompts the user to select focus areas, perspectives (up to 4), and analysis depth unless overridden by flags.
  • Initializes a discussion.md with session metadata, dimensions, depth, and initial questions.
• Step 2: Exploration (inline, no agents)
  • Detects codebase type via presence of common files (package.json, go.mod, etc.).
  • If a codebase exists, reads project metadata via spec loading commands and searches the codebase using contextually relevant patterns, focusing on modules, patterns, integration points, and constraints.
  • Writes findings to exploration-codebase.json and, for single perspective, explorations.json; for multiple perspectives, writes per-perspective findings to explorations/{Perspective}.json.
• Step 3: Interactive Discussion (multi-round, max 5)
  • Presents current understanding and exploration findings, gathers user feedback, and applies responses to deepen, adjust scope, or answer questions.
  • Updates discussion.md with round details and narrative synthesis; records intent drift checks and repeats until complete or max rounds.
• Step 4: Synthesis & Conclusion
  • Verifies intent coverage, consolidates insights into conclusions.json (with steps per recommendation), updates discussion.md, and offers interactive recommendation review.
• Step 5: Plan Generation (optional)
  • Generates an inline plan checklist appended to discussion.md and reminds execution via a specified downstream pipeline.

When to use it

• When you want an auditable, multi-round analysis that keeps a documented discussion timeline and traceable decisions.
• When exploring a topic with potential codebase implications and multiple analytical perspectives.
• When you need a structured path from topic understanding to actionable plans, with explicit recording of findings, decisions, and assumptions.

What it can touch

• Uses tools and file operations such as:
  • Writing and reading files like discussion.md, explorations.json, explorations/{Perspective}.json, exploration-codebase.json, perspectives.json, conclusions.json
  • Shell and JavaScript snippets to parse topics, detect codebases, and generate session IDs
  • Commands and file paths formatted in the skill (e.g., /codex:analyze-with-file, ANL-{slug}-{date}, discussion.md)

Caveats

• The workflow relies on user interaction for initial focus and perspectives unless auto mode (-y) is used.
• Exploration is described as inline with no agent delegation; actual execution depends on tool availability in the deployment environment.
• License is MIT as indicated by the skill metadata.