orchestrator-code-quality

What I do

• Operate strictly within the orchestrator/ folder.
• Produce a Markdown report describing:

1. Duplication / near-duplication 2. Over-complex functions / “god modules” 3. Inconsistent error handling and logging

• Use npm run check:all as the authoritative signal for tests + linting.
• Do not change code, configuration, scripts, or dependencies. This skill outputs a report only.

When to use me

Use this when you want an evidence-driven code quality assessment and a prioritized plan for remediation without implementing changes yet.

Constraints

• Work only in orchestrator/. Do not analyze or reference other folders except when required to understand imports into orchestrator/.
• Do not propose changes to tooling. Assume npm run check:all is the existing gate.
• Do not perform refactors. Do not open PRs. Do not rewrite files. Report findings and recommended fixes only.

Inputs I expect

• Repository access with an orchestrator/ directory.
• Ability to run npm run check:all from within orchestrator/.
• (Optional but recommended) Output logs from npm run check:all if the environment cannot run commands.

Process

1. Set working area

- Ensure all investigation is scoped to orchestrator/.

1. Execute quality gate

- Run npm run check:all in orchestrator/. - Capture: - lint errors/warnings (rule IDs, counts, file paths) - failing tests (test names, stack traces, determinism vs flakiness indicators) - coverage output (if produced by the command)

1. Assess duplication

- Identify copy/paste and near-duplicate logic patterns in orchestrator/: - repeated parsing/validation - repeated error mapping and response shaping - repeated API call wrappers / fetch patterns - repeated UI hooks/components with minor differences (if applicable) - Prefer evidence: - “same structure appears in files A/B/C” - “multiple implementations differ only by X/Y flags” - If the repo already includes duplication tooling, use it; otherwise rely on code inspection and minimal search.

1. Assess complexity hotspots

- Identify functions/modules with: - deep nesting - long functions - mixed responsibilities (validation + IO + transformation + logging) - difficult-to-test implicit dependencies - Provide concrete hotspots (file paths, function names) and why they’re hotspots.

1. Assess error handling and logging consistency

- Check for: - multiple error shapes (different status codes/messages for same category) - swallowed errors vs raw throws - missing context/correlation fields in logs - potentially sensitive data in logs - Identify boundary points (handlers, adapters) where standardization should occur.

1. Synthesize a fix plan

- Provide a prioritized plan with blast radius assessment and test needs. - Do not implement. Do not request changes. Report recommended actions only.

Report output format

Create a single Markdown report containing these sections:

1. Scope and constraints

• Confirm orchestrator/ scope and reliance on npm run check:all.

2. Evidence summary

• npm run check:all outcome:

- Lint: top rule IDs + counts + representative file paths - Tests: failing tests list + deterministic vs flaky notes - Coverage: summary if present

3. What’s wrong and why it matters

Include these subsections (at minimum):

3.1 Duplication and near-duplication

• Symptoms observed (with file-level examples)
• Why it matters in this repo
• What should be done to fix it (safe refactor tactics + tests needed)

3.2 Over-complex functions and “god modules”

• Hotspots (file paths + functions)
• Risk explanation (bug surface, change friction)
• What should be done (decomposition targets + boundaries + tests)

3.3 Inconsistent error handling and logging

• Inconsistencies found (examples)
• Operational/security impact
• What should be done (standard error types/mapping + logging conventions)

4. Fix strategy (prioritized)

• Phase 1 — Reduce duplication safely
• Phase 2 — Decrease complexity in hotspots
• Phase 3 — Standardize error handling and logging

Each phase must include:

• Ordered list of actions
• Expected blast radius (low/medium/high)
• Required test additions (if any)
• Validation steps (how to confirm improvement via npm run check:all)

5. Definition of done

• npm run check:all passes reliably
• Measurable reduction in targeted duplication clusters
• Complexity hotspots reduced or isolated behind clear boundaries
• Error/logging behavior consistent at boundaries
• No coverage regressions (if coverage is tracked)

Quality bar for recommendations

• Be specific: include file paths, function names, rule IDs, and observed patterns.
• Be conservative: prefer small, behavior-preserving refactors in the plan.
• Avoid “make it green” shortcuts:

- do not recommend disabling lint rules/tests as a first move - if quarantining a flaky test is suggested, include a concrete follow-up requirement and deadline policy