APK Reverse Engineering & Patching
Goal: reach a verified, installable, still-working artifact fast — and avoid the whole class of
mistakes that destroy an APK while looking completely healthy.
Immediate — do these four things before anything else
This file is a procedure with gates, not background reading, and it is long enough that its middle
gets skimmed. So the four moves come first; everything below is the explanation for them.
1. Classify before choosing a route. Answer the thirteen questions in §Start here. R4 decides
whether you are editing the right layer at all, and a wrong branch does not fail loudly — it produces
an artifact that builds, runs, and does the wrong thing.
2. Clear the four gates, in order, with their pass criteria (§Gates). G1 names the deliverable form
in one testable sentence before any work; G2 establishes what this machine can really do; G3 locates
the code; G4 records the baseline and the control. "I understand the idea" is not clearing a gate.
3. A symptom you cannot explain is a stop signal, not a puzzle. Search §Symptom index for the shape
before your next attempt and load the file that row names. Those rows exist because each one cost
hours — and in several cases the answer was already written down while it was being re-derived.
4. Two strikes on one shape of attempt sends you back to classification, not to a third variant
(§Stop conditions). And never report done without the six items in §What "done" means.
Two rules about this file itself. When a failure does not fit your plan, the symptom index is the
next action, not more reasoning. And when this file and your own reasoning disagree, this file wins
until you have evidence that overrides it: every rule here is the residue of a failure that cost
hours, and your current intuition is the intuition of someone who has not hit it yet.
Four rules that override everything else
R1 — Write the deliverable as a testable sentence before you touch the target.
"It works" is not the goal; "it works under the stated constraint" is. Root-assisted, live-
instrumentation, host-proxy and patched-device results frequently do
not satisfy a request for an
installable artifact that works on a normal phone — and it is easy to present such a result as
finished. Write the sentence, re-read it at every checkpoint, and if you cannot meet it, say so
plainly and label the privileged workaround a
fallback, never the deliverable.
→
references/long-task-discipline.md
§the most expensive drift
R2 — Change one variable at a time, and keep a control build.
An experiment that flips two things teaches nothing when it fails, and a failure you cannot attribute
will be attributed to the wrong cause. Every "the app rejects X" claim needs its own run, and every
patch needs a same-pipeline control that still fails the old way.
→
references/long-task-discipline.md
§single-variable discipline
R3 — Never ship or claim an unverified artifact.
"It assembles" is not "it works"; "the process started" is not "the feature works"; "no error in the
log" is not "the check is gone". Install it, launch it, exercise the exact feature you changed, and
look at the screen. Prove the device is running the build you made — hash it, do not trust the
filename.
→
references/verification.md
R4 — Identify the owning layer before patching, and re-classify when reality disagrees.
Ads, paywalls, feature gates, integrity checks and update gates live in different layers (Java, dex,
native, Dart/Unity, server). Patching the wrong layer either does nothing or breaks the app. If a
patch "had no effect", the diagnosis was wrong — go back to classification instead of patching harder.
→
, then the layer-specific file the symptom index points at
Tooling — reach for the right instrument, and check before declaring it absent
Most wasted rounds in this domain are not bad reasoning about the target. They are
the right question
asked of a tool too weak to answer it: an hour of
over a hand-exported smali tree where one
indexed query would do, a manual ELF walk where a decompiler was one
away. The failure is
invisible from the inside, because the weak route still produces output.
Five obligations. These are instructions; a violation is a defect, not a preference.
| Obligation | Do this | Cost of ignoring it |
|---|
| Orient with an indexer, not an export | Build the ability to ask the artifact questions before reading code: / (string/type/method → every reference site, sub-second). A decompile reads a class you have already located — it is not how you locate it. is a readable viewer of last resort, never the source of truth and never the entry point of a recon | hours of per question asked, over an export you paid for first |
| Install the missing tool; it is part of the task | A missing arm64 decompiler is the next step, not a constraint to route around. Ask a human only when installation is genuinely impossible | hours re-derived by hand for output a decompiler gives in minutes |
| Name the gap before spending against it | State the capability the blocker requires and whether this machine has it, out loud. This is a G2 item | designing around a tool that installs in ten minutes |
| Reach for a shipped script before writing one | Parsing, hashing, alignment and hot-plug probes are already written; a bespoke script in place of is how offsets get guessed instead of computed | a wrong offset that decodes cleanly and behaves wrongly |
| Pick the instrument for the layer the question lives on | A dex in memory wants (find and cut) plus (judge), not a decompiler pointed at a fragment. An algorithm you only have to call wants . "Does this class ever load at runtime" wants a hook that fires or does not | the heavier tool is not the safer one — it produces a plausible answer, which is worse than none |
Run python skills/apk-reverse/scripts/doctor.py --json
It reports per-capability closure — what is missing, what to install, and roughly how long that takes —
and a capability you have not checked for is not a capability you lack.
It is deliberately allowed to
report : a machine with a JVM but no
/
cannot re-sign, and the report
says so rather than inferring capability from a tool that is merely present. Detail:
; the registry it reads is
.
Coverage — what this skill claims, and what it does not
The failure this section prevents is not ignorance. It is a confident wrong answer produced by
applying the nearest available procedure to a target it was never written for. A documented method
that almost fits is more dangerous than no method at all, because it arrives with a plan, a
vocabulary and a set of reassuring numbers.
How strong these claims are — this is load-bearing, not cosmetic. Every claim in this skill carries
one of three labels, and you must label your own results the same way:
| Label | Means | May it justify a decision? |
|---|
| a command was run and its output exists | yes |
| follows from an observation, but the step is reasoned | provisionally |
| assumed, or reported elsewhere and never reproduced here | only as something to test |
The inventory that replaces a guess: the per-route list of what is covered and what is not — by
verified mechanism versus by documented-but-mostly-inferred route — is in
references/coverage-and-limits.md
. Load it when the question is "can this skill actually do X".
Partial coverage that is easy to over-read — these are documented routes whose dependency this
skill does not ship, and each has a fence around it in the same file: Dart AOT analysis needs a
snapshot dump you must obtain elsewhere and naming the front end matters · extraction-shell recovery
stops at the VMP boundary · a Stalker trace is not guaranteed on every device · a kernel-side answer
requires a module this skill only scaffolds.
Not covered — say so rather than improvise: Unity / IL2CPP · React Native / Hermes / Cordova ·
iOS · defeating a server-side authority · an off-the-shelf unpacker or an anti-detection arms race ·
building and shipping a kernel module. Reasons and evidence boundaries are in
references/coverage-and-limits.md
;
silence in that record is not support.
The fallback, as an instruction — this is a rule, not advice. If the target does not match the
covered list, or no symptom-index row matches, then stop and classify before choosing a branch:
answer the thirteen questions (§Start here). If the shape still does not fit — an unknown runtime, a
mechanism you cannot name — say exactly that and propose the cheapest experiment that would
identify it. Do not take the closest documented route and apply it anyway. A wrong branch here does
not fail loudly: it produces an artifact that builds, runs, and does the wrong thing.
Hand-off points — where this skill ends and another view begins
Four boundaries that are easy to walk into without noticing. Each names what the other side owns
rather than restating it, because two copies of the same advice drift apart. The JNI form table and
the per-form verification table live in
references/handoff-boundaries.md
.
- JNI — a Java declaration and its implementation are two views of one function, and
this skill reads each with a different tool. A symbol search fails silently on dynamic
registration. Authoritative treatment:
java2c-and-jni-sinking.md
- Hardening — a dex-side packer observation is a native-side implementation question.
owns the dex-side identification; the deep dive belongs on the other side.
- Native anomalies — read them from the APK side, because the judgement is whether your patch
caused the death. Restoring a symbol or reversing an OLLVM function is a different activity with a
different toolchain: point across instead of extending into it.
- Deliverable form — when the artifact stops being an APK, the verification question changes with
it. G1's other three forms each move the evidence somewhere else, and the failure is quiet: a
privileged result reported in the language of a finished build.
Symptom index — a matching row is a stop signal
You arrive at a symptom, not at a file name. Each row below is a failure that has already been paid
for. If any row matches what you are observing, load the file before your next command — not after
your next three attempts. Reasoning from first principles at this point is how the same hours get
spent twice; more than one entry here is a lesson that was re-derived by hand while the answer sat
unread in this repository.
| What you observe | Load first |
|---|
| A repackaged/re-signed build dies before your code runs; , all registers zero, , near | native-tamper-and-suicide.md
code-virtualization-and-custom-linkers.md
|
| No packer (Application is the app's own, dex readable) and it still dies | code-virtualization-and-custom-linkers.md
|
| The app dies at startup on every device, packed or not, with no tombstone while says and logcat says | a bundled crash reporter has taken the signal handlers, so the platform's own trail is gone. Frida spawn-gating is the recovery route |
A FORTIFY: pthread_mutex_lock called on a destroyed mutex
| — check is actually being loaded; Flutter's engine bootstrap is the usual place a native lifecycle fault surfaces |
| Log says a Java-layer signature/integrity check passed, yet the process dies | code-virtualization-and-custom-linkers.md
|
Deleting a library fixes validation but yields UnsatisfiedLinkError: dlopen failed: library "X" not found
| code-virtualization-and-custom-linkers.md
|
| Whole classes appear as bare declarations with no body | java2c-and-jni-sinking.md
|
| A search over a hardened library returns nothing at all | java2c-and-jni-sinking.md
|
| You are about to publish an evidence file, a transcript or a README that quotes real work | references/desensitization-and-leak-scans.md
|
| A hooking module appears to have run but its log tag is silent, and you are about to record "it never loaded" | references/precedents/logd-broken-module-never-ran-case-3.md
|
| A library's SONAME does not match its filename | code-virtualization-and-custom-linkers.md
|
| Your edit had no effect at all, with no error | server-config-and-updates.md
|
| Process hangs with no crash record, or dies to a killer | native-tamper-and-suicide.md
|
| Death looks like an ordinary null dereference in a hardened library | native-tamper-and-suicide.md
|
| The app dies only while you are attached/rooted | detection-and-anti-analysis.md
|
| Install fails with and mentions / alignment | §2a — STORED and 4-byte aligned, both required |
| Install fails with a bare numeric code (e.g. ) and no | §vendor install interception — a device-side interceptor, not your build. Use the root path |
| After an install, does nothing / screenshots show another app / hangs | §the installer may still own the screen |
Log shows Failure to verify dex file ...: Bad checksum
| §the dex header has two integrity fields — order matters |
| An install "succeeded" but nothing changed, or the version did not move | §keep the observation window clean |
| Evidence contradicts itself, or a capture looks like two states mixed | §keep the observation window clean |
| You took screenshots but drew the conclusion from logs or from the patch itself | §captures you never looked at are not evidence |
| You are about to re-run an experiment whose result you already recorded | §long-context decay |
| A script will not start, or a tool "is missing" | , then §"not on PATH" is not "not installed" |
| A hook or probe reports no events at all, and you are about to call it detection | scripts/anti_detect_probe.js
detection-and-anti-analysis.md
|
| hangs and then fails while the process is still in | detection-and-anti-analysis.md
|
| The app exits with no tombstone, no crash and no ANR record | detection-and-anti-analysis.md
|
| A dump region validates as the wrong thing, or an view of looks like a dex | §What this route cannot do, and how to tell before you spend the window |
| Feature-scoped network failure (login/register/pay) while the rest works | — do not assume your patch caused it |
| Everything works but every signed request fails after repack | signature-derived-keys.md
|
| A re-signed build runs fine, renders its whole UI and logs no error — but one feature silently never loads, and /DNS/logcat show no request for it at all (not a rejected request: no request) | code-virtualization-and-custom-linkers.md
|
| You cannot tell whether a missing feature is your patch's fault or the target's own behaviour | §single-variable discipline. Run the zero-change control through the same pipeline, and the decisive variant: the unmodified original with the patch applied in memory only, same device, same network |
| Under Frida , the UI never appears — stays , screenshots come back blank, the Activity stack never builds | §spawn keeps the Activity stack down: write the patch into memory, detach, then start the Activity normally |
| keeps disappearing mid-experiment, or the device reboots itself while you are working | §when the ROM hunts your instrumentation |
| Ads still appear after a patch that should have killed them | server-config-and-updates.md
|
| A forced-update or "must update" gate blocks the build | updates-and-forced-upgrade.md
|
| The dialog is gone but the feature is still locked | / — decide server vs client authority before patching again |
| You are about to discard a route as "blocked" | — re-read it before writing any route off; mis-attributed failures have removed viable routes for hours |
| The task has run long and you are unsure what is already proven | §keep a live record |
| A dumped dex parses in full, the classes are all there, and most method bodies are stubs or nop fills | references/advanced-unpacking.md
scripts/dex_dump_validate.py
|
Your dump dies mid-write (script has been destroyed
| §dumping when frida is refused — rule out memory pressure first; a reclaim-and-relaunch needs no instrumentation |
| A repack is refused by several independent checks, or the build has to keep working through store updates | references/lsposed-and-modules.md
|
| A hook module is installed, enabled and scoped, yet its log tag never appears — and you are about to conclude it never ran | §Deploy, enable, and verify — a -only verdict has already been wrong here: on one ROM is broken and output reaches only /data/adb/lspd/log/modules_<ts>.log
|
| A module's entry class is missing from its own dex (so it can never load), yet the package installs, enables and looks healthy | references/lsposed-and-modules.md
|
| You only need to call the target's own routine (sign, token, encrypt) rather than change the app | references/emulation-and-rpc.md
|
| A native function is a many-thousand-line state machine, or the decompiler's output is meaningless | references/native-dbi-and-deobfuscation.md
|
| installs but no events arrive, or following a hot libc export crashes the process | references/native-dbi-and-deobfuscation.md
|
| The traffic is protobuf/gRPC/QUIC, or a proxy sees TLS but requests still fail on a Flutter app | references/protocol-reverse.md
|
| Userspace hooks land and the app still dies: the check reads through a raw , or runs before | references/kernel-and-environment-hardening.md
|
| You must edit, repack, sign or inspect the APK from the phone itself | references/on-device-tooling.md
|
| A captured body decodes to nothing readable, or you cannot tell whether a length-delimited field is a string, a nested message or a packed array | . Protobuf on the wire (measured) — run scripts/protobuf_decode_raw.py
|
| Method bodies are present but decode as private opcodes, and you need the mapping rather than an explanation of why VMP is hard | vmp-differential-analysis.md
|
| A store build arrives as + , or a rebuilt build is refused as a set although every file verifies on its own | — one keystore across every member for , and check that a merge is legal before trusting a merged single APK |
Gates — clear these before you patch, in order
Each gate is an action with a pass criterion. Do not proceed past a gate you have not cleared, and
do not treat "I understand the idea" as clearing it. Skipping a gate is not a shortcut; it is how the
work gets redone.
G1 · Deliverable form — and the cost ceiling on it. State, in one sentence you could hand to
someone else, what artifact must exist at the end and under what constraints (rooted or not,
installable on a stock device or not, must survive updates or not, online or offline). Pass: the
sentence names a testable constraint, not an activity. Fail: you are solving a problem in an
environment the deliverable will never see.
Then name the form that sentence implies. "A rebuilt, self-contained APK" is only one of four, and
this is where the choice belongs — not after the repack has already failed:
| Form | Right answer when | What it costs you |
|---|
| Rebuilt, installable APK | The client owns the behaviour; no multi-point integrity check; no extraction shell | Repack, re-sign, and a device to verify on |
| LSPosed / Xposed module | The logic is client-side but the app fights repacks (multi-point signature checks, shell self-verification), or the result only has to work on rooted devices you control | A rooted device, module scaffolding, and an app that must not detect the hooking framework → references/lsposed-and-modules.md
|
| Local RPC / emulation service | You do not need to change the app — you need to call it: a signing routine, a token, an encryption function | A live device or an emulated loader plus a call harness → references/emulation-and-rpc.md
|
| Analysis report with a stated boundary | The authority is server-side, or the target is a real VMP / extraction shell whose recovery cost exceeds the value of the task | Nothing ships — and that is the honest answer, not a failure → references/advanced-unpacking.md
|
Decision trigger for leaving the first column: switch off "rebuilt APK" as soon as the evidence shows
(a) more than one independent integrity check that must all pass,
(b) an extraction shell whose
method bodies exist only at invocation time, or
(c) any body that decodes as private opcodes. At
that point the repack route is not merely expensive — it is blocked, and the deliverable sentence
should say which form replaced it.
A form chosen here and re-read at every checkpoint is the guard
against the most expensive drift in this skill (
references/long-task-discipline.md
).
G2 · Environment truth and capability inventory. Run
(and
if a device is in play).
Pass: you know which toolchains and scripts can actually run here, you have
seen the environment warnings — clock skew, leftover
/proxy, a device-side frida process
already running, a tool installed off-PATH —
and you have written down the capability this target will
demand against the capability this machine has. Name the two or three layers the task will almost
certainly reach (for example "arm64 native decompilation", "Dart AOT snapshot dumping", "device-side
TLS inspection", "dex-wide cross-referencing") and mark each available / missing-but-installable /
genuinely out of reach.
Fail: you are about to attribute to the target a failure caused by your own
setup — or to spend a day routing around a tool that installs in ten minutes. A layer whose tool is
missing is a
task item, not a constraint to design around. →
§Closing a
capability gap
G3 · Code location. From the manifest and dex, answer: is there a packer, where does the app's own
code live (dex / native / Dart / Unity / server), and is any of it virtualized to native. Pass: you
can name the class that owns the behaviour you intend to change, or you have an explicit plan to find
it. Fail: you are about to patch a layer you have not located. If recon says "no packer", still
check the virtualization shape — see the index rows above.
G4 · Baseline and control. Pass: you have a control run — the unmodified original, or a
zero-change repack through the same pipeline — and you have recorded the observed failure (including
time-to-death, if it dies). Fail: when the patched build misbehaves you will have nothing to
compare against, and every later measurement is unfalsifiable.
Start here: classify the target in thirteen questions
Answer these before touching a tool — all thirteen, in order. Each one changes the whole plan, and
a wrong answer here does not fail loudly: it produces an artifact that builds, runs, and does the
wrong thing. The answer column names both the action and the file that owns the detail; load that
file before acting on the question.
| # | Question | What the answer changes | Load |
|---|
| 1 | Is the app packed/hardened? Read the manifest's | A third-party shell class rather than the app's own Application means you have a packer and must handle it first | |
| 2 | Where does the behaviour actually live? — ad SDK · server-issued config for client-rendered UI · membership/VIP · feature flag or debug switch · anything decided by an API response | Client-side and removable, versus server-supplied data the client decides with, versus server-authoritative where a client patch is cosmetic. Decide this early: hunting an ad SDK that does not exist costs hours, and the server-config shape has no SDK to find | , server-config-and-updates.md
|
| 3 | Is the app's own code in plain dex, or moved to native / Flutter / Unity? | Which toolchain the whole task uses. Cheap runtime check before committing: hook the obvious Java classes for the UI you care about and reproduce that UI. Hooks that fire mean Java owns it; hooks that fire zero times while the UI is plainly on screen mean the runtime or native code draws it, and a dex-only plan will stall. Do not keep hunting in dex after a zero-hit probe — the most expensive wrong turn in this skill's history | §Where does the app's own code live, |
| 4 | What must the deliverable be able to do? Write it as a testable sentence and re-read it at every checkpoint | The most expensive drift in this skill: a runtime-only result (data edit, live hook, blocked hostname, host proxy) looks like success while failing the requirement. The axes: privilege (unrooted?), modification form (rebuilt artifact vs live instrumentation), ABI/device class, network, persistence, distribution (self-contained?). If the evidence already shows a deep extraction shell, a VMP, or more than one independent integrity check, re-answer against G1's four forms — the repack column may be blocked, not expensive | §the most expensive drift |
| 5 | Does the app verify its own signature, or does the server? | App-side means you must bypass it; server-side means re-signing silently breaks the app later | , |
| 6 | What is your device situation? — rooted real device, rooted emulator, or no device | Whether Frida is usable at all, and whether the deliverable can be tested where it will run. Run before your first experiment and again whenever a failure surprises you — device state, a dead device server, a leftover proxy and clock drift all masquerade as a broken patch | , P9 |
| 7 | Which architecture is actually executing? | reports what the device claims and what the package manager chose — neither is what runs. Only the live mapping is ground truth. An unmapped library, a translator in play, or a different ABI than assumed changes the plan more than any patch will | §Cross-architecture, |
| 8 | Is one specific feature failing at runtime (login, registration, payment, an API-backed screen) while the rest works? | A feature-scoped network failure is very often a TLS/certificate problem on one code path, not your patch. An app can carry two independent trust chains, so "other requests work" proves nothing. Rule this out in minutes before hunting a signature check | |
| 9 | Was the input a build you did not produce (a circulating "cracked"/"modded" APK)? | Such builds are frequently re-protected — sometimes with more layers than the original — and may carry injected components or endpoints. Never use one as a patching workbench | |
| 10 | Does the client sign its requests with its own signing certificate? | Grep for / / before the first repack. If that value feeds a native HMAC/DES routine, the rebuilt APK must hardcode the original certificate value at every read site, or every signed request fails while the app still launches and looks healthy. The single most expensive silent failure in a repack, and 15 minutes of grep prevents it | signature-derived-keys.md
|
| 11 | Does the app die on its own after a while — no Java stack, or a native crash that looks like a bug? | A hardened library rarely calls ; it more often arranges a fault (load a small constant, use it as a pointer) so the death looks like an ordinary defect. Two rules before touching anything: enumerate which mechanism actually fires (signal and tombstone split them apart), and neutralise by returning, never by making it not return — a spinning stub freezes the process and produces a symptom that looks nothing like the cause | native-tamper-and-suicide.md
|
| 12 | Will this build still be usable in a week? | Any version check, upgrade prompt or self-update path means an unpatched build can be switched off or replaced remotely. This is one or two edits and it decides whether the work is durable — part of the build, not a follow-up. Also check for a hot-update / remote-config channel, which restores removed behaviour with no version change at all | updates-and-forced-upgrade.md
|
| 13 | Does the request touch sign-in or phone binding ("no login required", "skip binding", "guest ok")? | Separating a client-side gate (patchable) from an account-scoped resource (the screen is empty because the server has no account to answer for — not patchable). Classify first; and never fabricate a session to satisfy a gate, which produces a state worse than being signed out | |
Long-task rule (a condition, not advice): if this is likely to run long, open
references/long-task-discipline.md
and keep its record updated as you go. Re-read its
refuted-conclusions and dead-routes sections before starting any experiment. Losing earlier findings
is the most expensive failure in this skill, and it is entirely preventable.
The workflow, end to end
Steps are ordered.
Skip a step only when its stated skip condition is met — "it seems
unnecessary" is not a condition, and it is the reason most of the failures in
happened.
Two-strike rule. If the same kind of attempt fails twice, stop and go back to classification.
Do not run a third variation of a hypothesis that has already failed twice. Two failures of one shape
means the model is wrong, not that the parameters need tuning — and the third attempt is where an
entire round gets spent confirming what the first two already said. Re-read the symptom index at that
point; it exists for exactly this moment.
- Preflight, then Recon — is the cheapest possible first command: it reports which toolchains and scripts can actually run here, and surfaces the environment facts that poison experiments (clock skew, leftover /proxy, a device-side frida process already running, a tool installed off-PATH). Then before anything else if a device is involved (it takes seconds and prevents a whole class of false conclusions), then . Manifest, package name, version, ABI, dex count, packer, embedded SDKs, where the app's own code lives. Ten minutes here saves hours. If it is packed, unpack before anything else ( §unpacking): you cannot patch code you cannot read, the encrypted payload lengths tell you which dumped dex is the original, and a memory dump must be de-duplicated by hash and structurally validated before any of it is trusted.
If recon says there is no packer but a re-signed build still dies, you are in the layer
references/code-virtualization-and-custom-linkers.md
references/native-tamper-and-suicide.md
- Extract strings and endpoints — build a picture of the app's API surface and SDK inventory from the dex string tables. No decompiler needed for this, and it is fast. Scripts: .
- Trace to the owning class — find the class that wraps the behavior (the app almost always wraps third-party SDKs in one helper). Reverse-lookup instructions:
references/dex-patching.md
- Decide the patch layer — client SDK call / client rendering / client data consumption / server contract. See the table in .
- Patch surgically —
references/dex-patching.md
references/byte-level-patching.md
scripts/dex_patch_bytes.py
references/byte-level-patching.md
- Repack and sign —
references/repack-and-sign.md
references/updates-and-forced-upgrade.md
references/account-gates.md
- Verify on device —
references/environment.md
references/verification.md
- Log what you learned — if a failure cost you more than thirty minutes, add it to . That file is the most valuable artifact in this skill.
What "done" means — do not claim it earlier
Every item below must be true before you report completion. Anything less is a checkpoint and must
be labelled as one, out loud, with what remains. Premature "done" is the most damaging thing you can
report, because it ends the investigation while the user believes the problem is solved.
- The artifact exists and its identity is recorded — path plus hash, not a filename.
- It was installed and launched on the environment the deliverable sentence names (G1/R1). If
that environment was not available to you, say so and label the result accordingly.
- The behaviour you changed is verified changed — by direct observation of the feature, not by
the absence of an error message. "The log is clean" is not evidence; "the screen shows X" is.
- The features it touches still work. You exercised them. A build that starts but whose affected
feature is dead is not a result.
- The original limitation is stated if any survives — with the coupling that causes it, so the
next person can decide whether to accept it.
- Nothing you did leaves the target or the device in a broken state unless that was the goal, and
any privileged workaround is labelled a fallback rather than the deliverable.
If items 1–4 hold but the environment was wrong, you have a prototype, not a deliverable. Say
"prototype" and name the gap.
Stop conditions — halt and re-classify, do not retry
These are moments where continuing to push forward is the wrong move. Each has cost hours somewhere.
- The same shape of attempt failed twice. See the two-strike rule above.
- A patch had no effect and you were about to try a third variant of it. No effect means the
diagnosis was wrong, not that the patch was unlucky. Re-classify the layer.
- A new failure has no place in your current model. That is the symptom index's trigger condition.
- You are about to write off a route as "blocked" without a control build proving the block is
the app's doing rather than your pipeline's. Mis-attributed blocks have removed viable routes.
- You are about to claim success on absence of errors. See §What "done" means.
- A measurement disagrees with a conclusion you already recorded as settled. Re-open the
conclusion; do not explain the measurement away.
Non-negotiable constraints
These are defects when violated, not preferences. Each row states the check that catches it, so
"did I comply" is a command you can run rather than a judgement you make about yourself.
| Constraint | Why it is absolute | The check |
|---|
| Inputs are read-only. Work on copies; keep a known-good baseline | an edited original destroys the only reference you can diff against | /hash the original before the first edit; for entry-level proof |
| One variable at a time, with a control build (same pipeline, zero patches) | a compound change that fails teaches nothing, and the failure will be attributed to the wrong cause | a control run exists and its result is recorded |
| Verify structure after every dex edit | a patch that assembles and dies at load looks like a patch that worked | : zero differences in class set and access flags for classes you did not intend to change |
| Never patch a widely shared method. Count callers first | a -shaped helper with 30 callers is not an ad-specific hook | on the method you are about to touch |
| Never make an API fail to suppress a UI element | a 404/400 an endpoint's other features depend on takes the whole screen with it — measured as a build that never leaves the launch screen | suppress at the data-consumption or render layer instead; if a request's path changes, that is the bug |
| Neutralise a native terminate path by returning, never by making it not return | a spin stub freezes the caller holding its lock; unrelated threads wedge and the symptom (hang, external kill, restart loop) looks nothing like the cause, with no crash record | return a benign value, prefer success () over failure (), never touch ////. native-tamper-and-suicide.md
|
| Look before you conclude, and look while you wait | a screen that is actually looked at answers in one step what coordinate-guessing cannot answer in five | capture and inspect; byte-identical samples mean nothing will change. , §look at the screen |
| Bound every command, and calibrate the bound from a measurement | an unbounded call turns a stall into "still working", which is indistinguishable from progress | time the operation once, record it, derive the deadline from it. §Bound every wait |
| Every claim carries a label — , or | "probably", "should be" and "in theory" are not findings, and an unlabelled guess propagates as a fact | requires a command and its output; nothing else may be written as established |
| "Done" means the user-visible outcome | a blocking dialog still on screen means the task is not done, however clean the log is | §What "done" means, all six items; absence of a log line is never evidence of success |
| Never discard a route on compound evidence | if a failure followed two simultaneous changes, the attribution is a hypothesis — mis-attributed failures have removed viable routes for hours | re-run the abandonment single-variable before writing it down |
| Prove the device changed before measuring anything | install success describes the request, not the app on disk | hash the on-device artifact against your build; otherwise every later observation describes the previous build |
| Attribute a failure to the right layer before patching again | a feature-scoped network failure is frequently the app's own TLS/certificate problem, and chasing a signature check that does not exist burns hours | run the unmodified original on the same device and network first () |
Reference index and script index
Both tables live in — one load gets you every reference file with when to
load it, and every script with what it does. They are deliberately not duplicated here: this file is
loaded in full every time the skill activates, and those two tables are about 140 rows of lookup data
that nobody needs until they have already decided what to do.
The symptom index above stays, because symptom to file has to be one hop: when something fails you
are not choosing a file, you are recognising a failure, and a two-hop lookup at that moment is exactly
how a stop signal gets skipped.
references/evidence-summary.md
is the one reference that answers the claim-strength question from
inside an installed copy: capability → one-line conclusion →
/
/
→ the
evidence that ships with the skill. Load it when a claim's strength decides whether you trust it and
the run record is not in front of you.
checks that this file and
still agree, that every
reference file is named there, and that every script is named there. CI runs it.