Skip to content

rumoii/rumo-engineering-skills / skills/rumo-coding-guidelines

rumo-coding-guidelines

Verified

Use when writing, fixing, or refactoring code in a software repository, as the baseline discipline alongside more specific skills. Ground every edit in the real code path, do only the requested work and what it necessarily implies, avoid speculative abstraction and drive-by edits, apply the risk gate to changes touching money, auth, data, interfaces, or other high-risk areas, and close with verification. Do not use alone for review-only, diagnosis-only, or question-answering requests.

Rumo Coding Guidelines

Every change should trace back to the request, the code path it touches, and evidence that it works.

When the user wants these rules active even when this skill is not loaded, offer the always-on block in references/agents-snippet.md. Only after the user agrees, add it to their AGENTS.md or CLAUDE.md with scripts/baseline_block.py --target <file> --install, which changes nothing outside its markers.

Before Editing

  • Read the repository's agent instructions (AGENTS.md, CLAUDE.md, nearby guidance) and follow them over these defaults.
  • Find the real entry point, call chain, configuration, and the existing pattern for this kind of change. Do not locate code from memory, screenshots, error summaries, or file names alone.
  • Check the dependencies, types, and documentation already in the project before writing replacement code or adding a package. Do not assume a library lacks a feature without checking its API.
  • When the request has several reasonable readings, state the trade-off. Resolve high-risk ambiguity first; rumo-clarify covers how.
  • When several repositories are involved, keep track of which ones were read, changed, and verified.
  • Apply the Risk Gate below before editing.

Risk Gate

Apply this gate on your own whenever you implement a change; the user does not need to name it.

  • High at once: money (amounts, charges, refunds); authentication, authorization, secrets, and credentials; database migrations; irreversible effects such as deleting data, sending messages, or paying out.
  • Rate first: durable data (writes, storage formats, bulk updates); concurrency; interfaces and formats other programs read (APIs, messages, configuration fields, exported files); untrusted input (uploads, SQL or shell commands built from input, deserialization, cryptography); personal data in storage, logs, or exports; deployment and infrastructure (CI, deploy scripts, permission policies, new or upgraded dependencies); and anything whose risk is unclear. Judge the consequence of a failure, how far it spreads, and whether it can be undone. Only a high rating enters the gate; explain a non-obvious rating in one line. A wording change in these areas does not qualify by location alone.
  • When high: write a test that would catch this kind of failure and watch it fail before the change, such as an outsider being refused, a boundary amount, or an old reader loading the new format. Name the one fact the change is safe because of, and prove it by running code rather than by argument. After the last edit, run the checks once more and report that run. Read references/high-assurance.md in full before starting; it adds the spec, check selection, and evidence report.
  • Review-only, read-only diagnosis, and test-planning requests keep their own boundaries: the rating informs the advice and authorizes no edit. Spec approval authorizes implementation and local checks only; commits, pushes, deployments, database writes, deletions, credential changes, dependency installs, and paid services keep their own approvals.

Scope Test

Before adding anything the user did not name, answer three questions:

  1. Did the user ask for it?
  2. Will the requested result fail without it?
  3. What concrete code, data, deployment fact, or user decision shows it is needed?

If the first two answers are no, leave it out and mention it only when the user would want to know. The goal is the smallest correct result, not the smallest diff: keep callers, tests, accessibility, security, existing-data migration, supported platforms, and deployment steps working whenever evidence shows they depend on the change.

While Editing

  • Build the thinnest version that works end to end through the real entry point, then add capability in layers that each still work.
  • Do not add generic abstractions, plugin points, configuration switches, or fallback frameworks for a single use.
  • Do not reformat, rename, reorder, or refactor neighboring code. Match the surrounding style even when you would choose differently.
  • Remove only the dead code this change created.
  • Do not keep obsolete paths alive with shims, dual writes, flags, or deprecation periods unless the current contract requires them. Before deleting a path, confirm its callers, generated outputs, and deployment references. Contracts with external, persisted, or deployed consumers follow rumo-interface.
  • Do not accept a stopgap whose stated purpose is to be replaced later. When you knowingly accept a limit, such as a size cap or an unhandled rare case, state the limit and what would make it worth revisiting in a comment beside the code. Record material architectural choices with rumo-plan.
  • Keep internal risk notes out of deliverables. Add a disclaimer or warning only when the user asked, a decision depends on it, or leaving it out would make the result false or unsafe.
  • Report unrelated problems you notice instead of fixing them.
  • At these moments read the matching entry in references/principles.md: before adding to or restructuring code, after two failed fixes for one symptom, when a requirement only fits through special cases, before writing stateful or heavily branching logic, when writing validation or adapters, when a behavior spans more than three files, before a repetitive edit, and before reporting a measured number.

Authorization

Treat review, explanation, and monitoring requests as read-only until the user asks for a change. When the request changes mode or scope, re-read it rather than carrying old assumptions forward. Stop searching, testing, or reviewing once the evidence answers the question.

Working With Other Skills

  • The user's task picks the main workflow; specialist skills add their checks to it rather than starting a workflow of their own.
  • A subagent dispatched for a specific task follows its brief: it does not start another workflow or delegate further.
  • Share one reading of the repository state, call chain, risk, and evidence across them, and close with one report that covers each skill's checks.
  • Reuse a check result while the code, configuration, and target version it ran against are unchanged; after any of them changes, rerun the checks it affects.
  • A high-assurance final run is always a fresh run after the last edit; earlier passes never replace it.

Task Flows

Match the task to one of these routes. For any route except a small edit or an investigation, whose rows below are complete, read references/task-flows.md for its steps and stop points before following it. A flow is a default route, not a checklist to copy; when you skip a step, say why in the final report. Tasks that fit none keep the rules above.

TaskRoute
Small editRead, edit, most relevant check, rumo-verify; no plan, no review
Defect fixrumo-debug proves the cause, failing test, fix, verification recipe, rumo-verify
Featurerumo-clarify if unclear, rumo-plan if multi-step, risk gate, thin slices, recipe, rumo-verify
InvestigationRead-only answer with evidence; how or why code works goes to rumo-explain; technical comparisons and feasibility research go to rumo-research
ResumeRead the handoff or decision record, check the actual repository state, continue
RefactorCover the behavior with tests, move in green steps, rerun the same tests
Performance problemBaseline measurement, profile, fix, same measurement again; report both numbers
Metric improvementFixed measurement, one logged attempt at a time, keep or revert, never loosen the target
Runtime diagnosisCapture the signal, narrow to one mechanism, confirm, map to source; diagnosis only
PrototypeName the decision, throwaway build outside the product, switchable variants, recommend
Visual parityBaseline screenshots, one component at a time, image comparison
Skill or prompt changerumo-prose, repository validators, and the repository's acceptance policy
Pull request follow-upOn request: conflicts, review comments, then checks (rumo-git-commit); never merge
PauseStop at a safe boundary, nothing irreversible, resume note; commit only on request

Close With Evidence

  • Turn the task into a checkable goal, for example: reproduce, fix, run the focused test.
  • Prefer focused tests, builds, linters, script self-tests, git diff --check, or a real request or page check. Use rumo-verify before claiming the change is ready.
  • When a check fails, report the command, the reason, and the remaining risk. When a check cannot run, say so; never substitute "should work".
  • In answers, explanations, and reports, say where each factual claim comes from: a run you made, code you read (file:line), or inference. Never state an inference as fact.

Before Handing Back

  • Every changed file and hunk belongs to this task.
  • No unrequested abstraction, option, or capability slipped in.
  • Existing dependencies and patterns were checked before custom code was added.
  • When handing back changed work, the final message separates what changed, what was verified, and what remains unverified or blocked. A read-only or planning turn reports what it found and what the user must decide next.
  • When the user corrected you twice or more in this task, or the same kind of mistake recurred, end with a one-line offer to review the session for lessons, at most once per session. Do not start the review or edit any skill or instruction file unless the user accepts. Use the rumo-reflect skill for the review when it is installed; otherwise list the lessons and change nothing without approval.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall