analyze-file

Analyze File (v2)

Performs LLM qualitative audit for a single source file. Inputs are provided by the caller agent; this skill does not run static tools or query GitNexus on its own — those are the orchestrator's job. The skill's sole output is the mirror document.

Inputs (provided by caller)

{
  "file": "<absolute path>",
  "role": "declaration" | "implementation" | "module",
  "phase": 1 | 2,
  "static_tool_results": [
      {"name": "clang-tidy", "exit_code": 0, "stdout": "<json>", "output_parser": "clang-tidy-json"},
      ...
  ],
  "graph_context": {                     # from mcp__gitnexus__context
      "imports": [...], "exports": [...],
      "callers": [...], "callees": [...],
      "hierarchy": {"parents": [...], "children": [...]},
      "impact": {"upstream_count": N, "downstream_count": M}
  },
  "shape_check": [...] ?,                # from mcp__gitnexus__shape_check (phase 2, API files only)
  "metrics": {"loc": ..., "cyclomatic": ..., "nesting": ...},
  "paired_mirror": "<markdown>" ?        # phase 2 implementation only
}

Output

A single mirror document at .codeanalyzer/mirror/<file>.md with this structure:

---
file: <abs path>
role: <role>
phase: <phase>
analyzed_at: <iso8601>
tool_versions: {<tool>: <version>, ...}
---

# <file basename>

## Role
<one-paragraph description of this file's role, informed by graph_context>

## Public API (declaration phase only)
- Classes, functions, macros exported. Bulk data from graph_context.exports.

## Dependencies
- Imports: (from graph_context.imports — compact list)
- Import impact: upstream=N, downstream=M (from graph_context.impact)

## Static Tool Findings
For each tool in static_tool_results, render a subsection with the tool's findings **verbatim** (parsed via output_parser into a normalized form).

### clang-tidy
- <line> [<check-id>] <message>
- ...

### cppcheck
- ...

## Shape-check findings (phase 2, API files only)
<per mismatch, one bullet with consumer path + mismatched property>

## LLM Qualitative Audit
**Only findings that static tools cannot express.** Focus on:
- Design anomalies, responsibility tangles, hidden dependencies
- Security model gaps, threat-model inconsistencies
- Idiomatic / framework misuse that produces correct code but bad intent
- Hierarchy and override patterns (pass 2+ only — use hierarchy context)

Do **not** re-flag issues already covered by static tools — reference them by tool name if you need to discuss.

## Recommendations
- Prioritize by upstream impact count (from graph_context.impact).
- Concrete, actionable (e.g., "Extract foo() into Bar helper — 3 upstream callers rely on current shape, preview rename impact with mcp__gitnexus__rename(target='foo', new_name='bar', dry_run=True) before changing signature").

## Cross-references
- Paired header/impl mirror: `.codeanalyzer/mirror/<paired>.md` (implementation files only)
- Hierarchy parent mirror(s): (from graph_context.hierarchy.parents)

Rules

• Never run tools yourself. Trust the caller's static_tool_results.
• Never call GitNexus. Trust graph_context.
• If static_tool_results is empty for a phase that declares tools, abort with an error (the orchestrator misbehaved).
• If the mirror file already exists, append under "Revision History" subsection instead of overwriting.