engi-readability-analysis

name

engi-readability-analysis

description

Use engi to diagnose whether Rust, Python, or TypeScript code is structurally recognizable to AI agents and humans, rank hard-to-change units, build evidence-carrying context packs, and produce measurable refactoring plans. Use when asked to assess AI readability, find code an agent will struggle to modify, prepare context for a code change, compare readability before and after refactoring, or evaluate engi itself on a package, project, or workspace.

Engi Readability Analysis

Use engi as a structural probe, then validate its signals against source evidence. Treat scores as navigation aids, not measurements of cognition.

Operating contract

• Default to read-only analysis. Do not edit the target unless the user explicitly requests a change.
• Use syntax-only unless the user authorizes a stronger execution mode. Do not run target build scripts, procedural macros, Python modules, Node scripts, or TypeScript plugins merely to diagnose readability.
• Keep the language, package/project, and task profile fixed while comparing results.
• Distinguish an extractor limitation from a code defect and an unavailable dependency.
• Say “no direct test reference detected,” never “untested,” unless separate evidence proves it.
• Do not treat budget omission as an unresolved dependency. Report frontier and omitted_due_to_budget separately.

1. Establish scope and invocation

Identify the project root, language, package name when applicable, target unit if supplied, task, test policy, and token budget. Prefer an 8,000-token budget unless the receiving model requires another limit.

Language is inferred from project markers. Pass --language rust|python|typescript when markers are ambiguous:

engi analyze --root <project> --language python --format table
engi rank --root <project> --language typescript --top 10

In a multi-package workspace, pass the Cargo package name:

engi analyze --root <workspace> --package <package-name> --format table

When engi is not installed but its repository is available, invoke it without installing:

cargo run --manifest-path <engi-repo>/Cargo.toml -- analyze \
  --root <workspace> --package <package-name> --format table

If a Rust package name is unknown, use Cargo metadata or engi's actionable package error. Do not silently merge multiple packages; analyze them separately and state that cross-package ranking is not available. Python and TypeScript syntax-only analysis uses tree-sitter; qualify runtime dispatch, dynamic imports, monkey patching, decorators, and generated definitions as extractor limitations rather than proven code defects.

Choose the task deliberately:

• implementation-change: target and forward dependencies; normal editing default.
• bug-fix: include test and reverse-impact context.
• contract-change or feature-addition: inspect callers, contracts, and tests.
• refactor: emphasize structural boundaries while preserving behavior.

2. Triage the package

Run package analysis and ranking:

engi analyze --root <workspace> --package <package-name> --format table
engi rank --root <workspace> --package <package-name> \
  --task <task> --budget <tokens> --top 10 --format markdown

Record elapsed time, exit code, unit counts, complete/partial/failed counts, unresolved count, candidate count, and the lowest-ranked units. An exit code of 2 is an invocation/configuration problem; correct the command before judging the target.

Select one to three low-scoring units that are relevant to the user's intended change. Do not optimize the repository-wide score blindly.

3. Inspect evidence for each selected unit

Run both commands under the same package, task, tests, and budget:

engi suggest --root <workspace> --package <package-name> \
  --task <task> --budget <tokens> --format json '<unit-selector>'
engi pack --root <workspace> --package <package-name> \
  --task <task> --budget <tokens> --format json '<unit-selector>'

Large JSON packs can overwhelm the conversation. Stream saved output through scripts/summarize.py, or parse only the fields listed below. Keep the original JSON available as evidence when file writes are authorized.

Inspect:

• source path and line;
• score, rating, and severity counts;
• target tokens, parameters, outgoing/incoming edges, SCC size;
• context units/files and rendered token total;
• direct test references, docs, and declared contract;
• frontier count and reasons;
• omitted fragment count, ratio, and first omitted units;
• proposed action, acceptance criteria, and verification commands.

4. Ground the findings

Open the reported source location and verify that each high-impact signal corresponds to real structure.

• Search the symbol with rg -n '<symbol>' <package-root> to check direct callers and direct test references.
• Inspect SCC members or cycle edges before proposing dependency inversion.
• Check whether a long unit actually contains separable phases, state transitions, or mixed side effects.
• Check whether omitted fragments are essential to the requested change; increase the budget or split the task when they are.
• Treat unresolved repository edges as global extraction debt unless they occur in the selected unit's frontier.

Downgrade or qualify any claim that source inspection does not support. Preserve engi's limitations in the report.

5. Produce a correction plan

Translate evidence into the smallest measurable intervention. Prefer plans such as:

• extract input normalization, decision, and effect application into named pure functions;
• represent a state transition with a small enum and transition function;
• replace a wide parameter list with a meaningful request value;
• break a verified cycle at one edge with immutable data or a port;
• add direct boundary tests without deleting broader integration coverage;
• repair extractor/configuration coverage instead of restructuring valid code.

For every action, include the evidence, expected AI/human benefit, acceptance criterion, and exact remeasurement command. Avoid generic “split the function” advice when the source reveals more specific phase boundaries.

6. Validate determinism or a requested change

For tool evaluation, run the same pack twice and confirm byte-identical output. Report warm-run timings separately from build/install time.

For an authorized code change:

1. Save the pre-change suggest --format json outside the target source tree when possible.
2. Make and test the smallest intervention.
3. Re-run with identical package, task, tests, budget, and profile.
4. Use --baseline <before.json> and confirm the addressed issue disappears without a new high-severity issue.
5. Check behavior tests independently; a better engi score is not proof of correctness.

Report format

Lead with whether engi produced an actionable result. Include:

1. scope and execution mode;
2. package-level completeness and timing;
3. ranked problem units with source links;
4. grounded findings, with false-positive qualifications;
5. prioritized correction plan and measurable acceptance;
6. engi limitations relevant to the result;
7. whether files were modified and the target Git status.

Script

Use scripts/summarize.py to reduce suggest or pack JSON to evidence fields without embedding rendered source fragments:

python3 <skill-dir>/scripts/summarize.py suggest.json
python3 <skill-dir>/scripts/summarize.py -