docs: add CODEX_RESUME_PROMPT.md for platform-side agent hand-off
Mirror of the trading repo's resume prompt but anchored on the
platform-side audit work. Any agent (Codex, Claude, Gemini, etc.)
running on this machine can paste in the short prompt at the bottom of
this file and self-bootstrap from the full brief above.
Brief covers:
- Required reads (HANDOVER.md + AUDIT_PLATFORM.md, optionally the
trading repo's HANDOVER for cross-repo context)
- Environment (source ~/.zshrc for GITEA_NPM_TOKEN — without it pnpm
install -r fails on the private @bytelyst/* mobile dep)
- Verification gates with explicit "error count must go down, never
up" rule
- Working-tree state: 3 nomgap WIP files + 1 regenerated lockfile
that the agent must NOT touch
- The P-sweep: 85 pre-existing lint errors, broken down by rule, with
a per-package workflow (one package = one commit) and a suggested
walking order
- Commit conventions matching the prior session
(chore(P-sweep): pnpm --filter <pkg> lint:fix)
- Seven explicit "do not" rules — the most important being do-not-
modify the audit's load-bearing eslint config block (`**/*.cjs` +
`**/scripts/**`) which prevents 45 errors from regressing
- When-to-stop-and-ask criteria so the agent doesn't blindly delete
"unused" exports that downstream repos (trading vendor) consume
Refs: docs/HANDOVER.md, docs/AUDIT_PLATFORM.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
69a4dc4340
commit
1f5dc1a812
254
docs/CODEX_RESUME_PROMPT.md
Normal file
254
docs/CODEX_RESUME_PROMPT.md
Normal file
@ -0,0 +1,254 @@
|
||||
# Codex Resume Prompt — Common Platform Audit
|
||||
|
||||
Paste the contents of this file into a fresh Codex / Claude / Gemini agent
|
||||
session running on the **same machine** that did the original work
|
||||
(`Sar-M2-bl`, user `saravana`). The agent will pick up the platform-side
|
||||
audit work and drive the open lint debt to zero.
|
||||
|
||||
The short "copy-paste" version of this prompt lives at the bottom of this
|
||||
file.
|
||||
|
||||
---
|
||||
|
||||
## ── BEGIN AGENT BRIEF ──
|
||||
|
||||
You are resuming a tooling-backed audit of a 69-package pnpm workspace.
|
||||
A prior session already unblocked the lint pipeline, ran every gate, and
|
||||
catalogued what's left. Your job is to clear the **85 pre-existing lint
|
||||
errors** that are now visible — one package at a time, with eyeball
|
||||
review, no shortcuts.
|
||||
|
||||
### Step 0 — Required reads (do this BEFORE writing any code)
|
||||
|
||||
Read these two files in order. They are the source of truth — anything
|
||||
contradicting them is wrong:
|
||||
|
||||
1. `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md`
|
||||
2. `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`
|
||||
|
||||
If you also plan to work cross-repo (the platform's vendored packages get
|
||||
re-shipped to the trading repo), also skim:
|
||||
|
||||
3. `/Users/saravana/BytelystAI/trading/learning_ai_invt_trdg/docs/HANDOVER.md`
|
||||
|
||||
After reading, summarise in your own words: which audit items are ✅ done
|
||||
(section A — 13 items), which are ⬜ open (section P — the 85 errors),
|
||||
and which package you are about to attempt first. If your summary
|
||||
disagrees with the audit doc tables, re-read.
|
||||
|
||||
### Step 1 — Environment
|
||||
|
||||
This machine has the private-registry token in `~/.zshrc`. **Every shell
|
||||
you spawn** must source it before running `pnpm`. Without it `pnpm`
|
||||
prints `WARN: Failed to replace env in config: ${GITEA_NPM_TOKEN}` and
|
||||
the install will fail on the private `@bytelyst/*` packages used by the
|
||||
mobile workspace and by transitive deps.
|
||||
|
||||
```bash
|
||||
source ~/.zshrc # gets GITEA_NPM_TOKEN onto your shell
|
||||
echo "$GITEA_NPM_TOKEN" | wc -c # must print 41 (40 chars + newline)
|
||||
```
|
||||
|
||||
### Step 2 — Verification gates (run BEFORE and AFTER every change)
|
||||
|
||||
You MUST run these before claiming any item ✅ done. If a gate fails
|
||||
after your change, you broke something — fix it before committing. Do
|
||||
NOT --no-verify. Do NOT skip hooks.
|
||||
|
||||
```bash
|
||||
cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat
|
||||
source ~/.zshrc
|
||||
|
||||
pnpm install -r --prefer-offline # → cache hit, finishes in seconds
|
||||
pnpm typecheck # → exit 0 (all 69 packages compile)
|
||||
pnpm test # → ~2,200 tests pass
|
||||
pnpm lint > /tmp/lint.log 2>&1 # baseline: exit 1, 85 errors
|
||||
|
||||
# After your change:
|
||||
pnpm lint > /tmp/lint-after.log 2>&1
|
||||
diff <(grep -c "errors" /tmp/lint.log) <(grep -c "errors" /tmp/lint-after.log)
|
||||
# Error count MUST go DOWN, never up.
|
||||
```
|
||||
|
||||
The 96 `no-console` warnings are intentional in CLI scripts and are NOT
|
||||
your problem. Focus on errors.
|
||||
|
||||
### Step 3 — Working tree state at handover
|
||||
|
||||
Three files are uncommitted in the working tree and were intentionally
|
||||
left alone by the prior audit. **Do not touch them.** They belong to an
|
||||
in-progress nomgap-on-Vercel migration owned by another contributor:
|
||||
|
||||
- `docker-compose.ecosystem.yml`
|
||||
- `products/nomgap/product.json`
|
||||
- `services/platform-service/src/modules/flags/seed.ts`
|
||||
|
||||
A fourth file — `pnpm-lock.yaml`, +2,938/-8,520 lines — is from the prior
|
||||
session's `pnpm install -r` regeneration. Don't commit it. If your work
|
||||
needs a clean lockfile, run install yourself and decide deliberately.
|
||||
|
||||
### Step 4 — Priority queue: the P-sweep
|
||||
|
||||
The 85 errors break down by rule:
|
||||
|
||||
| Rule | Count | Notes |
|
||||
| ----------------------------------- | ----: | -------------------------------------------------- |
|
||||
| `@typescript-eslint/no-unused-vars` | 67 | Mostly unused imports / unused destructured params |
|
||||
| `prefer-const` | 7 | `let` declarations never reassigned |
|
||||
| `no-redeclare` | 7 | Identifiers shadowing globals or duplicate imports |
|
||||
| `no-useless-escape` | 4 | Regex / string escapes that are no-ops |
|
||||
|
||||
Recent upstream work made `^_`-prefix vars an official escape hatch
|
||||
(`varsIgnorePattern`, `caughtErrorsIgnorePattern`,
|
||||
`destructuredArrayIgnorePattern`). Use that — don't delete identifiers
|
||||
that might be public API.
|
||||
|
||||
**Workflow per package** (one commit per package, no exceptions):
|
||||
|
||||
```bash
|
||||
# 1. Identify package owners by looking at the lint log
|
||||
grep -B 6 "[1-9][0-9]* problems" /tmp/lint.log | grep "/(packages|services|dashboards)/" | sort -u
|
||||
|
||||
# 2. Pick one. Run lint:fix scoped to it.
|
||||
pnpm --filter @bytelyst/<pkg> exec eslint . --ext .ts,.tsx --fix
|
||||
|
||||
# 3. Inspect the diff. The autofixer can:
|
||||
# - delete unused imports (usually safe)
|
||||
# - delete unused exports (BREAKING — public API)
|
||||
# - rename `let` to `const` (always safe)
|
||||
# - remove regex escapes (almost always safe; verify regex behaviour)
|
||||
git diff --stat
|
||||
git diff # eyeball every hunk
|
||||
|
||||
# 4. For unused vars the autofixer can't safely remove (function params
|
||||
# that satisfy an interface, destructured shape that documents the
|
||||
# contract), prefix with `_`:
|
||||
# function foo(req, _res, next) { ... }
|
||||
|
||||
# 5. Re-run gates for the package only:
|
||||
pnpm --filter @bytelyst/<pkg> typecheck
|
||||
pnpm --filter @bytelyst/<pkg> test
|
||||
pnpm --filter @bytelyst/<pkg> exec eslint . --ext .ts,.tsx
|
||||
|
||||
# 6. Commit:
|
||||
# chore(P-sweep): pnpm --filter @bytelyst/<pkg> lint:fix
|
||||
# Refs: docs/AUDIT_PLATFORM.md item P.
|
||||
|
||||
# 7. Push, then update docs/AUDIT_PLATFORM.md to add the package to a
|
||||
# new "P. Cleared packages" sub-table with the commit hash.
|
||||
```
|
||||
|
||||
Suggested order (estimated highest error count first — confirm by
|
||||
inspection):
|
||||
|
||||
1. `services/platform-service` — biggest service, likely biggest chunk
|
||||
2. `services/extraction-service`, `services/cowork-service`, `services/billing-service`, `services/growth-service`, `services/tracker-service`
|
||||
3. `packages/auth`, `packages/llm`, `packages/cosmos`
|
||||
4. `packages/datastore`, `packages/events`, `packages/event-store`
|
||||
5. `dashboards/admin-web`, `dashboards/tracker-web`, `dashboards/ux-lab`
|
||||
6. Everything remaining (one pass)
|
||||
|
||||
Target: 6–10 small commits, lint error count 85 → 0.
|
||||
|
||||
### Step 5 — Secondary work (after P-sweep is done)
|
||||
|
||||
| # | Item | What | Effort |
|
||||
| --- | ----- | ------------------------------------------------------------------------------------------------------------ | ------ |
|
||||
| 1 | R3 | Silence the `.npmrc` `${GITEA_NPM_TOKEN}` WARN with a graceful fallback | 30 min |
|
||||
| 2 | R4 | Add explicit `@azure/core-client@^1.10.0` to the two services using `@azure/cosmos` to silence peer warnings | 15 min |
|
||||
| 3 | (new) | Decide whether to commit the regenerated `pnpm-lock.yaml` (review the diff) | 1 hr |
|
||||
| 4 | (new) | Audit any package whose tests skip > 5% (look at `feedback-client`, `cowork-service`) — investigate why | 1-2 hr |
|
||||
|
||||
### Step 6 — Commit conventions
|
||||
|
||||
Match the prior session's conventions exactly so audit history stays grep-able:
|
||||
|
||||
- **One package per commit** for the P-sweep. Combining packages destroys
|
||||
blameability.
|
||||
- Subject: `chore(P-sweep): pnpm --filter @bytelyst/<pkg> lint:fix` —
|
||||
if the fix needed manual edits beyond `--fix`, use
|
||||
`chore(P-sweep): clear lint debt in @bytelyst/<pkg>`.
|
||||
- Body explains anything non-obvious: "renamed `_options` to satisfy
|
||||
interface; removed unused export X after confirming no consumers in
|
||||
workspace."
|
||||
- Reference: `Refs: docs/AUDIT_PLATFORM.md item P.`
|
||||
- End with `Co-Authored-By: <model> <noreply@anthropic.com>`.
|
||||
- After committing, **edit `docs/AUDIT_PLATFORM.md`** — add the package
|
||||
to a "P. Cleared packages" sub-table with the commit hash. Update the
|
||||
"remaining errors" count in section P intro.
|
||||
|
||||
### Step 7 — Things to NEVER do
|
||||
|
||||
1. **Do not touch the nomgap WIP files** (see step 3). Different
|
||||
contributor's in-flight work.
|
||||
2. **Do not commit `pnpm-lock.yaml` as a side effect.** If your work
|
||||
actually needs new deps, mention it explicitly in the commit body.
|
||||
3. **Do not bulk-fix multiple packages in one commit.** Each package
|
||||
needs eyeball review of the autofixer's diff. Combining them hides
|
||||
regressions.
|
||||
4. **Do not blindly accept `eslint --fix` for unused exports.** An
|
||||
"unused" export at the workspace level might be re-exported from an
|
||||
index file or consumed by a downstream repo (e.g. the trading repo
|
||||
vendors several `@bytelyst/*` packages and consumes them through
|
||||
barrel imports). When in doubt: prefix with `_` rather than delete.
|
||||
5. **Do not skip verification gates.** "It looks fine" is not
|
||||
verification. Run the commands and see exit 0.
|
||||
6. **Do not push --force to main.** Backup branch
|
||||
`backup/main-20260504-062733` exists for emergency rollback;
|
||||
rewriting public history is still wrong.
|
||||
7. **Do not modify the audit-fix eslint config block** (the `**/*.cjs`
|
||||
and `**/scripts/**` block in `eslint.config.js`) without
|
||||
understanding why it was added. It's load-bearing — removing it
|
||||
re-breaks 45 errors in design-tokens.
|
||||
|
||||
### Step 8 — When you finish a chunk
|
||||
|
||||
After each commit + push:
|
||||
|
||||
1. Run the verification gates **again** (push hooks may have reformatted
|
||||
files via `lint-staged`).
|
||||
2. Update `docs/AUDIT_PLATFORM.md` with the cleared package + hash.
|
||||
3. Tell the human: package name, commit hash, error-count delta. Three
|
||||
sentences max. Example:
|
||||
> Cleared `services/platform-service`: 23 → 0 errors via mostly-`--fix`
|
||||
> with two manual `_`-prefix renames in `modules/referrals`. Commit
|
||||
> `abc1234`. Workspace error count now 62.
|
||||
|
||||
### Step 9 — When to stop and ask
|
||||
|
||||
Stop and ask the human, do not guess, when:
|
||||
|
||||
- An "unused" export is consumed by code outside this repo (trading repo
|
||||
vendors several packages — check there before deleting).
|
||||
- A `lint:fix` autofix changes runtime behaviour (rare for the rules in
|
||||
scope, but possible with `no-useless-escape` if a regex is doing
|
||||
something subtle).
|
||||
- Tests start failing in a package whose code you didn't directly touch
|
||||
(transitive type breakage).
|
||||
- You have cleared all 85 errors and want direction on Section R or
|
||||
Section W.
|
||||
|
||||
Otherwise: keep going. The point of this brief is so you don't have to
|
||||
ping the human every package.
|
||||
|
||||
## ── END AGENT BRIEF ──
|
||||
|
||||
---
|
||||
|
||||
## Short copy-paste prompt for Codex
|
||||
|
||||
Paste this single block into Codex / Claude / Gemini:
|
||||
|
||||
```
|
||||
Resume the platform audit on this machine. Read
|
||||
/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/CODEX_RESUME_PROMPT.md
|
||||
in full first — it contains your full brief, the P-sweep workflow, the
|
||||
verification gates, and the commit conventions. Then walk the 85 lint
|
||||
errors package-by-package: pick one, run `pnpm --filter <pkg> exec
|
||||
eslint . --ext .ts,.tsx --fix`, eyeball the diff, run gates, commit
|
||||
(one package = one commit, subject `chore(P-sweep): ...`), push, tick
|
||||
the audit doc, repeat. Source ~/.zshrc in every shell so
|
||||
GITEA_NPM_TOKEN is available. Do not touch the nomgap WIP files. Do
|
||||
not bulk-fix. After each push, tell me the package, commit hash, and
|
||||
error-count delta in three sentences.
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user