hugoduncan/psi/review-implementation-architecture

review-implementation-architecture

Use this skill to review a completed or in-progress implementation for an architecture-level simplification task generated by the reduce-architectural-complexity workflow.

This skill reviews the actual implemented change, not the pre-implementation task design. It is distinct from review-task-architecture, which judges whether a Munera task design fits the project architecture before implementation.

Required orientation

1. Read the Munera task artifacts at the provided task path:

• design.md
• plan.md when present
• steps.md
• implementation.md

1. Read the selected target and evidence from task-local, worktree-root-relative files. Do not assume workflow context inlines these artifact contents:

• architecture-targets.edn
• target-issues.edn when present, otherwise target-issues-unavailable.edn
• before-diagnose.edn
• after-diagnose.edn
• after-architecture-targets.edn
• architecture-compare.edn
• architecture-gate.edn
• characterization-baseline.edn when present

1. Read the project architecture sources relevant to the touched area:

• AGENTS.md
• ramora/META.md
• doc/architecture.md
• any local architecture docs referenced by the task or touched namespaces

1. Inspect the implementation diff and the affected code/tests/docs. Prefer runtime/test evidence over prose claims.

Judgement criteria

Flag actionable feedback when any criterion below is not satisfied.

Behaviour preservation

• The change preserves externally visible behaviour named in the generated task.
• Characterization and affected-area tests cover the behaviour the architecture refactor could disturb.
• Validation failures, missing artifacts, or unreadable Gordian artifacts are not accepted silently.

Target fit

• The implementation addresses the selected architecture-targets candidate recorded in the task.
• If target-issues.edn is present, the implementation engages the observations, hypotheses, refactoring directions, review questions, and success signals without treating hypotheses as facts.
• If only target-issues-unavailable.edn is present, the implementation is still justified by architecture-targets.edn, before/after Gordian evidence, and project architecture sources.
• The review does not switch to a different target because a more interesting issue appears nearby.

Blast-radius discipline

• Production edits stay within :target/source-areas plus explicitly recorded :target/allowed-adjacent-source-areas.
• Adjacent-source edits have a task-local reason recorded before or during implementation.
• External namespaces mentioned by evidence are treated as review context, not implicit membership.
• Test edits stay tied to :target/affected-test-areas or newly recorded affected tests.

Architectural improvement / no regression

• The implementation improves or credibly reduces the selected architecture problem without introducing worse coupling, cycles, ownership blur, unstable shared dependencies, or hidden coordination.
• architecture-compare.edn, architecture-gate.edn, and after-architecture-targets.edn support the claimed outcome, or any non-moving metric is explicitly and plausibly explained for this slice.
• The change follows project boundaries: dispatch owns state mutation, resolvers own reads, effects stay at effect/runtime boundaries, adapters remain projections/entry points, and extensions remain isolated.

Simplicity and shape

• The change reduces architectural complexity rather than adding compatibility shims, adapters, broad indirection, or parallel models.
• New abstractions have one obvious owner and are locally comprehensible.
• Existing patterns are reused when they fit; new patterns are introduced only when the task evidence justifies them.

Output contract when used via review-step

Append a terse note to the task's implementation.md. Add unchecked follow-up items to steps.md for every new actionable issue. Avoid duplicating existing notes or follow-ups. End with exactly one of:

PASS_STATUS: ACTIONABLE_FEEDBACK

PASS_STATUS: REVIEW_COMPLETE