From 6a79cb52c5a3a69f533a50ac682776233b6ec59a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 12 Feb 2026 20:42:22 +0000 Subject: [PATCH] docs(agents): fix behavioral defects in agent prompts (P2) - Remove AI generation artifacts (:contentReference) from docs-code-investigator (4 occurrences) - Fix require() -> import in event-schema-agent example (project uses ES modules) - Clarify nonexistent script reference in const-refactor-agent (scripts/find-numeric-literals.js must be created, not assumed) - Close truncated code blocks and add TODO notices in interop-agent and smoke-agent (both missing Failure Modes and Outputs sections) No agent mission changes. https://claude.ai/code/session_01Nz6FJopPp2YHEscJrRAFNv --- docs/agents/prompts/daily/bitvid-const-refactor-agent.md | 4 ++-- .../agents/prompts/daily/bitvid-docs-code-investigator.md | 8 ++++---- docs/agents/prompts/weekly/bitvid-event-schema-agent.md | 2 +- docs/agents/prompts/weekly/bitvid-interop-agent.md | 7 ++++++- docs/agents/prompts/weekly/bitvid-smoke-agent.md | 8 +++++++- 5 files changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/agents/prompts/daily/bitvid-const-refactor-agent.md b/docs/agents/prompts/daily/bitvid-const-refactor-agent.md index e69ba99b..822ad97a 100644 --- a/docs/agents/prompts/daily/bitvid-const-refactor-agent.md +++ b/docs/agents/prompts/daily/bitvid-const-refactor-agent.md @@ -60,8 +60,8 @@ DETAILED WORKFLOW (step-by-step) ``` - (Adjust regex to include more candidates you want.) - For a more robust approach, run an AST scan (Node/ES module) to find numeric literals: - - If comfortable, use `node` + `acorn` or `@babel/parser` script `scripts/find-numeric-literals.js` to produce JSON output of numeric literals with file, line, column, and nearby AST context (identifier or property name). - - Example (conceptual): + - If comfortable, use `node` + `acorn` or `@babel/parser` to create a script (e.g., `scripts/find-numeric-literals.js`) that produces JSON output of numeric literals with file, line, column, and nearby AST context (identifier or property name). + - Example (conceptual — script must be created first): ``` node scripts/find-numeric-literals.js js > perf/constants-refactor/numeric-literals.json ``` diff --git a/docs/agents/prompts/daily/bitvid-docs-code-investigator.md b/docs/agents/prompts/daily/bitvid-docs-code-investigator.md index 5e76cb33..b824e1df 100644 --- a/docs/agents/prompts/daily/bitvid-docs-code-investigator.md +++ b/docs/agents/prompts/daily/bitvid-docs-code-investigator.md @@ -6,11 +6,11 @@ This document is your operating manual. Follow it exactly for every file you doc =============================================================================== WHY / SCOPE / PRIORITY -- Why: The project prefers moving complex UI logic into controllers and keeping `js/app.js` thin. Large or understudied files (especially under `js/nostr/*`, `js/services/*`, or `js/app.js`) carry the most maintenance risk and highest documentation value. See `AGENTS.md` on "bitvidApp vs. UI Controllers". :contentReference[oaicite:0]{index=0} +- Why: The project prefers moving complex UI logic into controllers and keeping `js/app.js` thin. Large or understudied files (especially under `js/nostr/*`, `js/services/*`, or `js/app.js`) carry the most maintenance risk and highest documentation value. See `AGENTS.md` on "bitvidApp vs. UI Controllers". - Scope: - Target JS files under `js/` — prefer `js/nostr/*`, `js/services/*`, `js/app.js`, or large controllers. - Focus on files > ~200 LOC, or files that contain `TODO|FIXME|XXX`. -- Priority: files containing `TODO|FIXME|XXX` or >200 lines. Nostr helpers and signaling modules are high-value places to document. :contentReference[oaicite:1]{index=1} +- Priority: files containing `TODO|FIXME|XXX` or >200 lines. Nostr helpers and signaling modules are high-value places to document. =============================================================================== HARD CONSTRAINTS & GUARDRAILS @@ -134,7 +134,7 @@ TESTS & QA (must run before PR) npm run test:unit ``` -- If `package.json` exposes a test script, run that exact command (see `package.json`). :contentReference[oaicite:3]{index=3} +- If `package.json` exposes a test script, run that exact command (see `package.json`). - If linting is enforced, run linter: ``` @@ -227,7 +227,7 @@ OUTPUTS & ACCEPTANCE =============================================================================== FINAL NOTES - Be explicit about the reasons and the invariants — future contributors rely on these docs. -- If you propose moving logic to controllers, include a short extraction plan referencing `AGENTS.md` refactor checklist. :contentReference[oaicite:2]{index=2} +- If you propose moving logic to controllers, include a short extraction plan referencing `AGENTS.md` refactor checklist. - If you find cryptographic issues, stop and open `requires-security-review`. - Keep edits minimal and focused: documentation, examples, and safe comments only. diff --git a/docs/agents/prompts/weekly/bitvid-event-schema-agent.md b/docs/agents/prompts/weekly/bitvid-event-schema-agent.md index 1531be24..e0697f70 100644 --- a/docs/agents/prompts/weekly/bitvid-event-schema-agent.md +++ b/docs/agents/prompts/weekly/bitvid-event-schema-agent.md @@ -68,7 +68,7 @@ WORKFLOW - Responsibilities: - Import canonical APIs: ```js - const { getNostrEventSchema, buildVideoPostEvent, sanitizeAdditionalTags, /* ... */ } = require('../../js/nostrEventSchemas.js'); + import { getNostrEventSchema, buildVideoPostEvent, sanitizeAdditionalTags, /* ... */ } from '../../js/nostrEventSchemas.js'; ``` - Provide a configurable set of example inputs for each builder. - For each builder: diff --git a/docs/agents/prompts/weekly/bitvid-interop-agent.md b/docs/agents/prompts/weekly/bitvid-interop-agent.md index fde8536c..7c4eaba3 100644 --- a/docs/agents/prompts/weekly/bitvid-interop-agent.md +++ b/docs/agents/prompts/weekly/bitvid-interop-agent.md @@ -136,4 +136,9 @@ EXAMPLE RUN (illustrative) ```bash # required: RELAY_URLS="wss://relay.test.example" node scripts/agent/interop-test.mjs \ - --burst=3 --timeout=30 --out=artifacts/interop-2025-07-14.json \ No newline at end of file + --burst=3 --timeout=30 --out=artifacts/interop-2025-07-14.json +``` + + \ No newline at end of file diff --git a/docs/agents/prompts/weekly/bitvid-smoke-agent.md b/docs/agents/prompts/weekly/bitvid-smoke-agent.md index e485f576..7879d5cf 100644 --- a/docs/agents/prompts/weekly/bitvid-smoke-agent.md +++ b/docs/agents/prompts/weekly/bitvid-smoke-agent.md @@ -154,4 +154,10 @@ RELAY_URLS="ws://localhost:8080" node scripts/agent/smoke-test.mjs \ # public relays only with explicit confirmation and extreme throttle RELAY_URLS="wss://relay.example" node scripts/agent/smoke-test.mjs \ - --confirm-public --burst=1 --timeout=30 --out=artifacts/ \ No newline at end of file + --confirm-public --burst=1 --timeout=30 --out=artifacts/ +``` + + \ No newline at end of file