docs: retro for ADFA-5141 (doc-db page_size pin)

CLAUDE.md

@@ -37,7 +37,7 @@ See **[ARCHITECTURE.md](ARCHITECTURE.md)** — the single source of truth for th
 
 - **Avoid new dependencies** — the build almost certainly already has what's needed. Check `gradle/libs.versions.toml` and `build.gradle.kts` first.
 - **Persistence:** prefer **Room** for relational data and the filesystem/preferences for settings; raw SQLite only for justified exceptions — see [ADR 0001](docs/adr/0001-prefer-room-for-persistence.md).
-- **Don't treat a large binary asset's on-disk content as ground truth without checking its provenance first.** Run `git ls-files <path>` / `git check-ignore -v <path>`, and grep the build files for how it's provisioned, before relying on its current schema or row content. Several assets here (e.g. `assets/documentation.db`, and the SDK/bootstrap/Gradle zips alongside it) are `.gitignore`d and fetched by a Gradle task from an external URL (see the `Asset(...)` list in `app/build.gradle.kts`) — a locally-cached copy can be stale independent of git commit history and silently diverge from the maintained original.
+- **Don't treat a large binary asset's on-disk content as ground truth without checking its provenance first.** Run `git ls-files <path>` / `git check-ignore -v <path>`, and grep the build files for how it's provisioned, before relying on its current schema or row content. Several assets here (e.g. `assets/documentation.db`, and the SDK/bootstrap/Gradle zips alongside it) are `.gitignore`d and fetched by a Gradle task from an external URL (see the `Asset(...)` list in `app/build.gradle.kts`) — a locally-cached copy can be stale independent of git commit history and silently diverge from the maintained original. `documentation.db`'s generation/schema is owned by the separate `appdevforall/OfflineDocumentationTools` repo (`docdb-studio` tool), not this repo — see [docs/documentation-database.md](docs/documentation-database.md) before assuming a fix belongs here.
 - **Protect the two Android system bars** in any UI work: the top status bar (clock, notifications, status icons) and the bottom navigation bar (home, back, recents). Don't draw over or intercept them.
 - **Plan and size before building.** Prefer **one PR per ticket/use case** — don't force-split a coherent change (splitting has its own overhead when later edits span the pieces). When a change is large, break it into **reviewable commits** — mechanical/refactor commits separate from behavioral ones — and offer review-by-commit. Treat ~500 LOC / ~10 files as a signal to reach for that commit structure, not a hard cap; the ceiling rises as LLM-assisted review matures. For staged multi-commit refactors (e.g. removing a dependency across many files/modules), order stages easiest-to-hardest and independently compile/test each stage (see Build & test's fast-iteration guidance) before moving to the next, so a failure is isolated to the stage that caused it.
 - **Keep docs in step with code.** When you change code, update the docs that describe it in the same change — a module's `README.md`, `ARCHITECTURE.md`, or an ADR — so a doc never outlives the API it documents (see REVIEW.md, Code quality). If the doc fix is out of scope, file a ticket rather than let it drift.
@@ -71,7 +71,7 @@ Anything official or public-facing runs only through version-controlled GitHub A
 
 ### Jira tickets — read, and keep updated
 
-Read tickets with the local authenticated `jira` CLI (e.g. `jira issue view ADFA-1234`), configured via `JIRA_API_TOKEN`, `JIRA_HOST`, and `JIRA_USER`. Don't start the Atlassian MCP OAuth flow for reads — it's unnecessary when the CLI works.
+Read tickets with the local authenticated Jira CLI, configured via `JIRA_API_TOKEN`, `JIRA_HOST`, and `JIRA_USER`. The binary may be named `jira` or, when installed via snap, `jira-cli` (e.g. `jira-cli issue view ADFA-1234`) — if `jira issue view ...` fails with a permission or not-found error, run `which jira-cli` before retrying. Don't start the Atlassian MCP OAuth flow for reads — it's unnecessary when the CLI works.
 
 **Post progress as you go.** The team wants visibility into in-progress work, not just a final drop. When you start a ticket, hit a notable blocker or decision, or finish a meaningful chunk, add a short comment (`jira issue comment add ADFA-#### "…"`). Keep it crisp — status, what changed, what's next.
 

docs/process/learnings.md

@@ -7,6 +7,9 @@
 ## Git / GitHub
 - Before pushing a follow-up commit to a community PR, check `gh pr view <n> --json headRepositoryOwner` — the PR head is usually on the contributor's **fork**, so a same-named push to `origin` doesn't touch the PR and just creates a confusing dead branch that has to be deleted.
 
+## Jira CLI
+- On a snap install, the Jira CLI binary is named `jira-cli`, not `jira` — running `jira issue view ...` fails with `Permission denied (os error 13)` (a misleading error for "command not found"). If `jira` isn't on PATH, try `jira-cli` before assuming the CLI itself is broken.
+
 ## Android / Kotlin
 - `Handler.removeCallbacks(Runnable)` only removes callbacks posted by that *exact* `Handler` instance, not just the same `Looper` — `Handler(Looper.getMainLooper()).removeCallbacks(x)` won't cancel something posted via a *different* `Handler` bound to the same looper. Any post/cancel pair needs to share one `Handler` instance (see `TaskExecutor.mainThreadHandler`, added when replacing blankj's `ThreadUtils.getMainHandler()`).
 

docs/process/retrospective.md

@@ -1,5 +1,42 @@
 # Retrospective Log
 
+## 2026-08-14 - ADFA-5141: pin doc-db page_size to 2048
+
+### Time Breakdown
+
+| Started | Phase | 👤 Hands-On Time | 🤖 Agent Time | Problems |
+|---------|-------|-----------------|---------------|----------|
+| Aug 14, 11:57pm | Setup: switch branch, read ticket via Jira CLI | ▎ ~2m | ▏ ~1m | ⚠ `jira` binary not found; real command was `jira-cli` |
+| Aug 14, 11:59pm | Discover doc-db generation lives in a separate repo (`OfflineDocumentationTools`), clone it, implement `PRAGMA page_size` fix, add test, run full suite | | ██████████ 9.5m | |
+| Aug 15, 12:09am | Rename `PAGE_SIZE`→`UI_PAGE_SIZE`, commit, push, open PR, delete empty branch | ▏ ~1m | ███ 3m | |
+| Aug 15, 12:13am | Jira progress comment, retro (transcript analysis, feedback, CLAUDE.md audit + edits, learnings) | ▊ ~2m | ████████ 8m | |
+
+### Metrics
+
+| Metric | Duration |
+|--------|----------|
+| Total wall-clock | ~27 min |
+| Hands-on | ~5 min (19%) |
+| Automated agent time | ~21.5 min (81%) |
+| Retro analysis time | ~1 min (script run) |
+
+### Key Observations
+- **jira/jira-cli confusion**: CLAUDE.md's Jira instructions assumed the binary is named `jira`; on this machine it's a snap install (`jira-cli`), and the wrong name fails with a misleading `Permission denied` rather than "not found". Cost a few failed attempts before trying `jira-cli` directly. Fixed via CLAUDE.md edit (see Actions).
+- **Good independent-agent stretch**: a single one-word "yes" from the user launched a long unattended phase — Explore agent locates the real doc-db generation repo, clone it, implement + test the fix — with no further hands-on needed until it was ready to commit.
+- **Correctly avoided wasted work in the wrong repo**: the ticket was initially branched in `codeonthego`, but investigation showed the actual fix belongs in `OfflineDocumentationTools`/`docdb-studio`; the empty `codeonthego` branch was cleanly deleted rather than left dangling.
+
+### Feedback
+**What worked:** Good discovery + delegation (agent located the actual doc-db generation repo); fast pace with minimal back-and-forth.
+**What didn't:** Not directly confirmed by the user this round — the jira/jira-cli friction above is an inferred observation from the transcript, not user-flagged.
+
+### Actions Taken
+
+| Issue | Action Type | Change |
+|-------|-------------|--------|
+| `jira` vs `jira-cli` binary confusion | CLAUDE.md | Jira section now notes the binary may be `jira-cli` (snap) and to check `which jira-cli` before retrying |
+| Doc-db generation location required an agent search to discover | CLAUDE.md | Asset-provenance bullet now points to `OfflineDocumentationTools`/`docdb-studio` and `docs/documentation-database.md` |
+| `jira`/`jira-cli` naming quirk | Learnings | Added "Jira CLI" entry to `docs/process/learnings.md` |
+
 ## 2026-08-13 - ADFA-5088: individual Preferences/Plugin Manager tooltips + docdb SQL scripts
 
 ### Time Breakdown