From a2a0a97f23af9bab5c8f2d0be25f3dc9eb3a86ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Tajchert?= <michal.tajchert@lite.tech>
Date: Wed, 29 Apr 2026 01:40:50 +0200
Subject: [PATCH] docs: call out BuildConfig.java and adopt a two-tier endpoint
 doc template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two small changes that together meaningfully reduce wasted effort:

1. Phase 3 now explicitly tells the agent to read every BuildConfig.java.
   These files are almost never obfuscated and routinely contain the
   single highest-signal constants in the APK — base URLs, flavor names,
   build types, third-party API keys, feature flags. They were not
   mentioned in the previous workflow despite being the cheapest possible
   high-value target. One grep, finds them all.

2. The Phase 5 documentation template was a single per-endpoint block
   asking for path params, query params, request body, response type,
   and call chain. On apps with 100+ endpoints that easily becomes hours
   of work for output the consumer will not read.

   Replace it with two tiers:

     * Tier 1 — flat table covering every endpoint (host, method, path,
       auth required, source file). Always produced. Takes ~5 minutes
       from the --paths output.

     * Tier 2 — the existing detailed block, but explicitly reserved for
       high-value endpoints: the entire auth flow, payment/checkout, and
       anything the user specifically asked about. Default cap of ~10
       Tier-2 entries unless asked for more.

   This matches the natural shape of how analysts actually use this work
   (one inventory table to know the surface area, plus a deep dive on
   auth and a couple of flows) and prevents over-investment in detail
   for endpoints nobody will read about.
---
 .../android-reverse-engineering/SKILL.md      | 45 +++++++++++++++----
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/plugins/android-reverse-engineering/skills/android-reverse-engineering/SKILL.md b/plugins/android-reverse-engineering/skills/android-reverse-engineering/SKILL.md
index 7e3277b..f804a65 100644
--- a/plugins/android-reverse-engineering/skills/android-reverse-engineering/SKILL.md
+++ b/plugins/android-reverse-engineering/skills/android-reverse-engineering/SKILL.md
@@ -148,7 +148,13 @@ Navigate the decompiled output to understand the app's architecture.
    - Distinguish app code from third-party libraries
    - Look for packages named `api`, `network`, `data`, `repository`, `service`, `retrofit`, `http` — these are where API calls live
 
-3. **Identify the architecture pattern**:
+3. **Read every `BuildConfig.java`** — these are almost never obfuscated and frequently leak the highest-signal constants in the entire APK (base URLs, flavor names, build type, third-party API keys, feature flags):
+   ```bash
+   find <output>/sources -name BuildConfig.java -exec grep -H '=' {} \;
+   ```
+   Each Gradle module emits its own `BuildConfig`, so expect 1–N hits. Read all of them.
+
+4. **Identify the architecture pattern**:
    - MVP: look for `Presenter` classes
    - MVVM: look for `ViewModel` classes and `LiveData`/`StateFlow`
    - Clean Architecture: look for `domain`, `data`, `presentation` packages
@@ -242,15 +248,32 @@ On Windows (PowerShell):
 & "${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/scripts/find-api-calls.ps1" <output>/sources/ -Auth
 ```
 
-Then, for each discovered endpoint, read the surrounding source code to extract:
-- HTTP method and path
-- Base URL
-- Path parameters, query parameters, request body
-- Headers (especially authentication)
-- Response type
-- Where it's called from (the call chain from Phase 4)
+Document the endpoints in **two tiers** — going deep on every endpoint is
+prohibitively expensive on apps with 100+ paths, and most of them do not
+warrant it. Always produce Tier 1; expand Tier 2 only for the endpoints
+that matter.
 
-**Document each endpoint** using this format:
+#### Tier 1 — flat inventory (always)
+
+A single table covering every discovered endpoint. Aim for one line each;
+if you cannot determine a column, write `?`.
+
+| Host | Method | Path | Auth | Source file |
+|------|--------|------|------|-------------|
+| `api.example.com` | GET | `/v1/users/profile` | Bearer | `com/example/api/UserApi.java` |
+| `api.example.com` | POST | `/v1/auth/login` | none | `com/example/api/AuthApi.java` |
+
+This table answers "what does the backend look like" in one screen and
+takes ~5 minutes to produce from the `--paths` output even on a large app.
+
+#### Tier 2 — per-endpoint detail (only for high-value endpoints)
+
+Reserve the detailed format for the few endpoints that actually need it:
+
+- the entire authentication flow (login, refresh, logout, OTP/SMS, anonymous, registration)
+- payment / checkout / order-creation endpoints
+- anything the user explicitly asked about
+- anything that looked unusual during the scan (custom signing, undocumented headers, etc.)
 
 ```markdown
 ### `METHOD /path`
@@ -265,6 +288,10 @@ Then, for each discovered endpoint, read the surrounding source code to extract:
 - **Called from**: `LoginActivity → LoginViewModel → UserRepository → ApiService`
 ```
 
+As a default, do not produce Tier 2 entries for more than ~10 endpoints
+unless the user explicitly asks for more — Tier 1 plus a Tier 2 deep dive
+on auth + 1-2 key flows is what most consumers of this work actually want.
+
 See `${CLAUDE_PLUGIN_ROOT}/skills/android-reverse-engineering/references/api-extraction-patterns.md` for library-specific search patterns and the full documentation template.
 
 ## Output