pi: edit prompts

home/progs/pi.nix

@@ -239,9 +239,74 @@ in
       For using `nix build` append `-L` to get better visibility into the logs.
       If you get an error that a file can't be found, always try to `git add` the file before trying other troubleshooting steps.
       Never `grep` or `find` over the entire `/nix/store`, this is wasteful and will usually turn up weird results or will timeout.
+      - Before editing any file, always `read` it with an explicit line range
+        (e.g. `path/to/file:1-100`), never as a bare path. Without a selector,
+        the tool returns a structural summary with no line anchors, and the
+        edit will fail with "lines shifted" — wasting a round-trip.
 
       ## Implementation
       When sketching out an implementation of something, always look for tools that already exist in the space first before implementing something custom. This is also the case when it comes to submodules and sections of code, I don't want you to implement things in-house when it isn't needed.
+      ## Code Review
+      When working on a section of code (a function, a module block, a config stanza), you MUST run a multi-round adversarial review. Subagents are one-shot, so you chain rounds by feeding each round's full transcript into the next.
+
+      ### Round 1 — ELI5
+      Explain every line in plain English as if to a five-year-old. Do not skip lines, summarize groups, or hand-wave. State what each line does, why it's there, and what it assumes.
+
+      ### Round 2 — Attack
+      Spawn a reviewer subagent (via `task`) with the original code and your ELI5. Its sole job: find flaws — bugs, edge cases, incorrect assumptions, missing error handling, race conditions, off-by-one errors, performance traps, logical contradictions. It MUST NOT praise or sugar-coat; it must argue against the code.
+
+      ### Round 3 — Rebuttal
+      Address every finding point-by-point. For each: either acknowledge it and describe your fix, or rebut it with a concrete reason the reviewer is wrong. Do not dismiss findings without a specific counter-argument.
+
+      ### Round 4 — Second Opinion
+      Spawn a fresh reviewer with the full transcript (original code + ELI5 + attack findings + your rebuttals). Its job: did you properly address every finding? Are your rebuttals valid? What did Round 2 miss? If it finds new unresolved issues, return to Round 3 for those. Cap at 3 attack rounds total.
+
+      Amend your code based on every substantiated, unrebutted finding before proceeding.
+      ## Upstream contributions (patches/)
+
+      When working on patches against an external project under `patches/`,
+      you are submitting code to a codebase you did not write. You MUST learn
+      its conventions before touching anything, or the MR will be rejected.
+
+      ### Before writing code
+      - Find the project's file-registration mechanism (build system, i18n
+        file list, module registry) and add every new file to it. Projects
+        reject MRs that add orphaned files.
+      - Scan adjacent code for API conventions. If you see two ways to do the
+        same thing (e.g. legacy raw setters vs. modern type-safe wrappers),
+        use the newer/cleaner one. Do not copy-paste old patterns.
+      - Look for higher-level abstractions that do what you need in one call.
+        If the project already has a "replace entire payload" method, don't
+        mutate fields one by one.
+
+      ### Behavioral claims require evidence
+      - Comments that claim parity with an external system or specification
+        MUST cite a specific source. Unsubstantiated claims will be challenged
+        in review.
+      - Before implementing protocol-level behavior, verify the expected
+        behavior against a reference implementation or specification. Do not
+        guess.
+
+      ### Comments
+      - Write comments for the non-obvious "why", not the "what". Do not
+        explain how the framework or widget tree works unless the behavior is
+        genuinely surprising.
+      - Do not write comments that are factually wrong. If you don't know
+        whether a claim about library behavior is true, either verify or omit
+        the comment. Wrong comments are worse than no comments.
+
+      ### Architecture
+      - Prefer the simplest implementation that works. Remove redundant
+        wrappers, duplicate callbacks, and unnecessary nesting before
+        submitting.
+      - Before building a custom widget or container, check whether the
+        platform toolkit already provides the pattern. Consult actual docs;
+        do not guess about API capabilities.
+
+      ### Commit hygiene
+      - Never commit binary files (images, test data) to the repo. Use
+        existing project assets or generate test data at runtime.
+      - After changes, verify the code compiles and tests pass.
     '';
 
     ".omp/agent/skills/android-ui/SKILL.md".text = ''