diff --git a/CLAUDE.md b/CLAUDE.md index dc3b64ee94..3368b6d331 100644 --- a/CLAUDE.md +++ b/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 ` / `git check-ignore -v `, 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 ` / `git check-ignore -v `, 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. diff --git a/docs/process/learnings.md b/docs/process/learnings.md index 7c4224a00d..8d0bb953d3 100644 --- a/docs/process/learnings.md +++ b/docs/process/learnings.md @@ -7,6 +7,9 @@ ## Git / GitHub - Before pushing a follow-up commit to a community PR, check `gh pr view --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()`). diff --git a/docs/process/retrospective.md b/docs/process/retrospective.md index fb4eeadd34..0cc5b24cb0 100644 --- a/docs/process/retrospective.md +++ b/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