simplify

Simplify for Codex

This generated file is the Codex-facing runtime skill document. Codex should read this file directly; maintainers edit the source documents listed below instead.

Generated Runtime Composition

Source order:

• ../../docs/skill-core/simplify.md
• ../../docs/platforms/codex-runtime.md
• ../../docs/platforms/codex-simplify.md

The sections below are already composed for this platform. Do not ask the runtime model to load another platform's runtime document or invocation syntax.

Source: docs/skill-core/simplify.md

Simplify

Simplify reviews changed code for reuse, simplification, efficiency, and altitude issues, then applies behavior-preserving fixes.

It is a skill, not an agent. In Oh No Harness, ralph uses it after the selected mode's required review is satisfied and before final verification; the active platform runtime document supplies the matching simplify skill.

This is quality cleanup, not bug hunting. Use code-reviewer or the host's code-review workflow for correctness bugs.

Software Development Stage

Simplify is the post-implementation cleanup stage.

Use it after behavior is locked and the review required by the caller has passed or has been recorded as not needed. It should improve reuse, clarity, maintainability, and efficiency without changing behavior, adding scope, or replacing implementation review.

Cleanup Depth Decision

Reuse, Simplification, Efficiency, and Altitude are review viewpoints, not four mandatory jobs.

• LIGHT and STANDARD: run one quick or combined scan over all four viewpoints. Record no candidates when the scan finds nothing; do not create cleanup work to satisfy a pass count.
• THOROUGH without a named expansion trigger: use the same combined scan.
• THOROUGH with a named safety, broad-diff, multi-system, or high-maintainability risk: run four independent viewpoint passes. They may run in one parallel batch when isolation and platform policy permit it, otherwise run four labeled inline blocks and record the fallback.

Record Cleanup depth: combined | four-viewpoint, its trigger, and the changed files inspected. Use subagents only when separate contexts can change the cleanup decision enough to justify lifecycle cost. If cleanup creates a need for additional review or evidence, return it to the caller; Simplify does not expand its own mandate.

When To Use

Use for changed code that works but needs a quality pass before delivery:

• new code re-implements helpers the codebase already has
• logic can be simplified without changing behavior
• independent work is run sequentially or redundant work is repeated
• startup, hot paths, or tests do unnecessary I/O or computation
• fixes sit at the wrong altitude, such as fragile special cases on top of shared infrastructure
• Speculative abstraction, configuration, or generalization is not required by the current behavior
• comments, wrappers, or test details obscure the intended behavior

Do not use when the requested change is functional behavior, a broad refactor, or a rewrite without a behavior lock.

Required Behavior Lock

Before editing, establish one of:

• passing tests that cover the changed surface
• a focused verification command
• a manual acceptance checklist
• a clear before/after behavior description when no command exists

For a cleanup that alters control flow, structure, or shared/altitude mechanisms, an executable lock — passing tests or a focused verification command — is required; a prose lock (checklist or before/after description) suffices only for purely local edits. If only a prose lock exists for such a change, record it as reviewer follow-up under the Maintainability Debt Boundary instead of applying it.

If no behavior lock exists, create a verification plan first and state the risk.

Maintainability Debt Boundary

Simplify may fix behavior-preserving cleanup inside the reviewed diff, but it must not hide correctness, scope, security, or architecture concerns inside a cleanup pass. When a finding points to maintainability debt that cannot be fixed without changing behavior, widening scope, changing public contracts, or touching sensitive behavior, record it as deferred reviewer work instead of patching around it.

Classify every nontrivial finding as:

Maintainability finding:
- Type: behavior-preserving cleanup | reviewer follow-up | out-of-scope
- Evidence:
- Cost if ignored:
- Safe cleanup action:
- Reviewer needed: none | code-reviewer | plan-reviewer | verifier

Use reviewer follow-up for brittle coupling, unclear ownership, hidden state, cross-boundary special cases, fragile tests, risky generated changes, or cleanup that would require a behavior decision.

Scope

When called by ralph, limit cleanup to files changed in the current Ralph session.

When called directly, limit cleanup to the target files or paths named by the user.

Do not expand scope because nearby code looks messy.

If a PR number, branch name, or file path was passed as an argument, review that target instead of the default diff.

Phase 0 - Gather The Diff

Run git diff @{upstream}...HEAD to get the unified diff under review. If there is no upstream, use the smallest credible fallback such as git diff main...HEAD, git diff master...HEAD, or git diff HEAD~1.

If there are uncommitted changes, or the range diff is empty, also run git diff HEAD and include working-tree changes in scope. Treat this diff as the review scope.

Phase 1 - Review

Apply the Cleanup Depth Decision. A combined scan checks Reuse, Simplification, Efficiency, and Altitude in one bounded pass. When a named THOROUGH trigger selects four-viewpoint depth, launch the four independent cleanup subagents in one batch before waiting, or use four labeled inline blocks with a recorded dispatch-unavailable reason. The caller captures and cleans up every dispatched result.

Each pass returns findings with file, line, a one-line summary, and the concrete cost: what is duplicated, wasted, fragile, or harder to maintain. Each pass must also classify whether the finding is behavior-preserving cleanup, reviewer follow-up, or out-of-scope under the Maintainability Debt Boundary.

Reuse

Flag new code that re-implements something the codebase already has. Search shared utilities and files adjacent to the change, and name the existing helper or local pattern to use instead.

Simplification

Flag unnecessary complexity the diff adds: redundant or derivable state, copy-paste with slight variation, deep nesting, dead code left behind, or Speculative abstraction. Name the simpler behavior-preserving form.

Efficiency

Flag wasted work the diff introduces: redundant computation or repeated I/O, independent operations run sequentially, or blocking work added to startup, tests, or hot paths. Name the cheaper behavior-preserving alternative.

Altitude

Check that each change is implemented at the right depth, not as a fragile bandaid. Special cases layered on shared infrastructure are a sign the fix is not deep enough. Prefer generalizing the underlying mechanism over adding special cases, but skip anything that would change intended behavior or exceed the reviewed scope.

Phase 2 - Apply The Fixes

Capture the combined result or all four expanded results, then deduplicate findings that point at the same line or mechanism and fix each remaining behavior-preserving cleanup directly.

Skip any finding whose fix would change intended behavior, require changes well outside the reviewed diff, or that is a false positive. Note the skip rather than debating it.

Run the behavior lock again after cleanup. If the post-cleanup behavior lock regresses from the pre-cleanup result, revert the offending cleanup before reporting. If cleanup changed structure, tests, or control flow, return that need to the caller so code-reviewer or verifier can inspect the result.

Output

Return:

• Behavior lock used.
• Files changed.
• Cleanup depth, trigger, and review viewpoints covered.
• Cleanup findings fixed.
• Reviewer follow-up findings and owner.
• Findings skipped and why.
• Verification commands and results.
• Residual risk.

Next Skill Handoff

None - this is a post-implementation mid-loop skill. Return control to the caller (ralph or direct invocation). If the cleanup pass changed structure, tests, or control flow, recommend code-reviewer or verifier to the caller; do not invoke them yourself.

Source: docs/platforms/codex-runtime.md

Codex Runtime Rules

This compact platform section is embedded in generated Codex-facing skill documents.

Skill Loading

Codex-facing public skills live under skills/. Generated skills/<skill>/SKILL.md files compose the matching skill core, this compact runtime section, and any Codex skill-specific overlay such as docs/platforms/codex-<skill>.md.

User Approval And Prompting

Ask approval, preference, scope, or next-step questions directly in the Codex conversation. Keep prompts outcome-first: state the desired outcome, acceptance criteria, non-goals or side effects, expected evidence, and output shape before detailed steps.

Use compact final answers unless the active skill requires a plan, review, or verification report. Preserve durable state in written artifacts before long work, compaction, or handoff.

Role Dispatch

Dispatch only after the active skill's trigger fires, then read docs/platforms/codex.md ## Role Dispatch for the full host contract. Use spawn_agent(agent_type="oh-no-<role>", ...) first, do not combine it with fork_context=true, and use generic prompt embedding only after the custom agent is actually rejected. The task packet carries scope, ownership, expected output, and lifecycle.

Every dispatched result is a dependency: wait_agent must reach final status, the caller captures and uses the output, and only then performs lifecycle cleanup. Timeout, empty output, or "No agents completed yet" is not final; do not close, redo inline, or use missing output as evidence.

Generic Role Prompt Fallback

After confirmed custom-agent unavailability, embed docs/agent-core/<role>.md; see the full platform doc for the fallback shape.

Cross-Host Consult Channel

This channel is trigger-loaded, not embedded in every workflow decision. When a named THOROUGH paired-review or Fusion Rescue trigger fires, read and apply docs/platforms/codex.md ## Cross-Host Consult Channel before dispatch. Until then, do not preload opposite-host invocation details.

Source: docs/platforms/codex-simplify.md

Codex Simplify Rules

This platform overlay is source content for the generated Codex-facing simplify runtime document, after the shared core and docs/platforms/codex-runtime.md.

Cleanup Dispatch

On Codex, the CODEX_ONLY_OH_NO_SUBAGENT_STANDING_AUTHORIZATION SessionStart context is the standing explicit user request for Simplify cleanup delegation. Do not ask another approval question merely to launch eligible cleanup subagents.

Launch the four cleanup passes via Codex spawn_agent following the shared core's one batch before waiting dispatch rule; if Codex subagent dispatch is unavailable, use the core's inline labeled-block fallback. The core owns the batch, inline-fallback, and fallback-reason rules; do not restate them here.