Project: doctolib-doctolib · Branch: master · Mode: · Model: claude-sonnet-4-6 Stats: 1 user messages, 1 tool calls, tools used: Bash. Conversation Turn 1 — User Please review the following prompt against prompt engineering best practices and provide actionable feedback for improvement. This is the third iteration of a prompt. Previous scores: v1=3/5, v2=3/5. Changes made from v2 to v3: - ✅ Fixed double slash in oxygen path (@/Users/... instead of @//Users/...) - ✅ Added package placement reasoning instruction to step 8 - ✅ Clarified "Other tasks" ordering to "Remaining tasks — ordered by dependency (each task's parent must appear before it)" Issues flagged in v2 review that were NOT addressed: - ❌ Confluence URL still has no fallback (requires authenticated access — the agent cannot read it without a session) - ❌ "Doctolib development guidelines" still a dangling reference (no path to CLAUDE.md or style guide) - ❌ No concrete output task example/skeleton to anchor expected depth - ❌ Entry point PNG filename may be wrong (nhr-list-entry-point.png vs actual entry-point.png on disk) --- PROMPT TO REVIEW (v3): You are a Staff Frontend Software Engineer at Doctolib and will read a Tech Scoping https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View from the Doctolib's confluence page and divide the implementation in tasks to be implemented by a team of Junior Software Developers at Doctolib in between 1-3 days max effort. The task must be implemented according with Doctolib development guidelines and meant to be included into JIRA in the future. As constraint, it is expected that order of tasks: 1. Feature switch implementation 2. Create the NHR Entry Point (task 1 is a dependency) 3. Open the NHR Document List Modal (task 2 is a dependency) 4. Remaining tasks — ordered by dependency (each task's parent must appear before it) The tasks can have partial implementation that will be fulfilled later by another task: "Open the NHR Document List Modal" task does not need to render the table or the data, it can render an empty modal full size. Another task will be responsible for create the table placement with a title, a patient and dummy filters and columns, for an example. Output Format: The expected output will be a list of tasks in markdown format at @tmp/nhr-document-list/nhr-document-list-tasks.md - Title - Description/Objective - Acceptance criteria / tests - Dependency between tasks The Description/Objective must at minimun explain what is going to be implemented, how it fits in the overall project, the filepath of the target files, a code with implementation reference and mocked data for testing. The acceptance criteria must include: - Conditions for Unit tests expected - Correct Package/folder placement - How to test on staging. The dependency between task must describe the task which is the direct parent/parents and direct child/children. Suggested actions: 1. Read the Tech Scoping from https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View from the Doctolib's confluence page. 2. Read the design from Figma at https://www.figma.com/design/D5jfoP7Ed1teAOvL0yH2gV/%F0%9F%87%AB%F0%9F%87%B7--MOOSE--DMP-Segur-V2-2026?node-id=3187-100822&p=f&t=GQWhsn8E7ggBFibE-0. If Figma is not accessible, read the basic designs at @/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/NHR Document List.png and @/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-list-entry-point.png 3. Read the code base from @/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp 4. Read the code base from @/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records 5. Read the code base from @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records 6. Read the code base from @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui 7. Read the oxygen code base from @/Users/USER/workspace/doctolib/oxygen 8. Pre-write findings on @tmp/nhr-document-list/nhr-document-list-tasks-findings.md. For each planned task, record which package/folde …(truncated, 1337 more chars) Turn 1 — Assistant Prompt Review: v3 (Third Iteration) --- PROMPT SCORE: 3.5/5 (delta: +0.5 vs v2) --- QUICK ASSESSMENT - Context & Role: ✅ - Clear Staff FE Engineer role with domain specificity - Structure: ✅ - Numbered steps, ordered constraints, explicit output format - Examples: ⚠️ - One partial example (empty modal) but no concrete task skeleton showing expected depth - Reasoning: ⚠️ - Pre-write findings step forces intermediate reasoning, but no explicit "explain your decisions" instruction - Control: ✅ - File paths, format, section requirements all specified --- STATUS OF PREVIOUSLY FLAGGED ISSUES 1. Confluence URL fallback — NOT FIXED (blocking) The primary source of truth has no fallback. If the agent cannot authenticate to Confluence (which it cannot in a headless session), it proceeds with zero domain knowledge. Steps 2-9 all depend on step 1 succeeding. The agent has no instruction to gracefully handle a 401/403 and no alternative source (e.g., a local export, a summary paragraph in the prompt itself). 2. "Doctolib development guidelines" dangling reference — PARTIALLY FIXED The CLAUDE.md path (/Users/USER/workspace/doctolib/doctolib/CLAUDE.md) is described in the context section of this review but is NOT referenced inside the prompt body itself. The agent receiving only the prompt text has no pointer to CLAUDE.md. It still sees "Doctolib development guidelines" with no actionable path. 3. No concrete task example/skeleton — NOT FIXED The modal example ("render an empty modal full size") hints at partial implementation scope but gives no structural skeleton. Without a filled-in example of one task showing Title/Description/Acceptance Criteria/Dependency at the expected depth, junior-developer-ready output depth is ambiguous. 4. PNG filename — NOT FIXED nhr-list-entry-point.png is still unverified against what is actually on disk. Tools used: - Bash: ls /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/ 2>/dev/null || echo "directory not found" Tool results: → result (ok): code-1-2.png code-1.png code-2.png code-3.png DMP certification.xlsx Documentation_eSanteConnect-JSON-2.1.0_EN.md entry-point.png NHR Document List-loading-v2.png NHR Document List-v2-basic copy.png NHR Document List-v2-basic.png NHR Document List-v2-filtering-combined-criteria.png NHR Document List-v2-filtering.png NHR Document List-v2.png NHR Document List.png nhr-architecture-v2.drawio nhr-architecture.drawio NHR-document-list-1.png NHR-document-list-2.png nhr-document-list-tech-scoping-propo …(truncated, 149 more chars) The PNG filename concern is partially moot: both nhr-list-entry-point.png AND entry-point.png exist on disk. However, based on the directory listing, there is now a more significant finding. --- NEW ISSUES INTRODUCED IN V3 New Issue 1 (high impact): Local tech scoping file ignored The directory contains nhr-document-list-tech-scoping-v2.md and nhr-document-list-tech-scoping-proposal-v2.md at /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/. These are almost certainly the exported Confluence content and would serve as the exact fallback needed for issue 1. The prompt does not reference them at all, meaning if Confluence fails the agent has no fallback despite the answer sitting on disk. New Issue 2 (medium impact): Design PNG explosion not reflected The directory now has 9+ design PNGs (NHR Document List-v2.png, NHR Document List-v2-filtering.png, NHR Document List-loading-v2.png, etc.). The prompt only references NHR Document List.png and nhr-list-entry-point.png. The agent will miss loading states, filtering UI, and combined criteria states that are directly relevant to task decomposition. New Issue 3 (low impact): pre-write-findings.md already exists The output file pre-write-findings.md already exists in the directory. The agent may overwrite or append inconsistently. No instruction handles this collision. --- ARE THE REMAINING UNFIXED ISSUES BLOCKING? | Issue | Blocking? | Rationale | |---|---|---| | Confluence fallback | YES - High | Agent cannot read Confluence without auth. With nhr-document-list-tech-scoping-v2.md on disk and unlinked, the agent will either hallucinate domain context or produce tasks with no grounding in the actual spec. | | Dangling guidelines reference | YES - Medium | Without a path to CLAUDE.md, the agent falls back on generic React/TS conventions and may produce tasks that violate monorepo-specific rules (engine boundaries, package placement, background migrations, etc.). | | No task example/skeleton | YES - Medium | "Junior developer ready, 1-3 days" is subjective. Without a filled skeleton, the agent calibrates depth independently and likely produces either too shallow or too verbose tasks. Consistency across 6-8 tasks is unlikely. | | PNG filename | NO - Low | Both filenames exist. Not blocking. | --- PRIORITY-ORDERED REMAINING CHANGES 1. Add local tech scoping as primary source, Confluence as optional enrichment Replace step 1 with: "Read the tech scoping from @/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tech-scoping-v2.md. Optionally, attempt to load https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View for additional context if accessible." This eliminates the single point of failure with zero cost. 2. Add explicit path to CLAUDE.md for development guidelines Replace "Doctolib development guidelines" with: "Follow the development guidelines in @/Users/USER/workspace/doctolib/doctolib/CLAUDE.md, particularly the Engine Communication rules, TypeScript mandatory requirements, and package placement conventions." One sentence, removes ambiguity entirely. 3. Expand the Figma fallback to include all relevant PNGs Step 2 fallback should reference: NHR Document List-v2.png, NHR Document List-v2-filtering.png, NHR Document List-loading-v2.png, NHR Document List-v2-filtering-combined-criteria.png, nhr-list-entry-point.png. Loading and filter states directly map to tasks. 4. Add a one-task skeleton to anchor expected output depth Add a section like: "Each task must follow this structure depth (example below):" followed by a skeleton for the Feature Switch task with placeholder values filled in. Two hours of upfront structure investment prevents 6-8 inconsistently shallow tasks. --- FINAL VERDICT: NOT READY TO RUN The prompt is well-structured and v3 fixes are meaningful, but the two blocking issues (Confluence auth wall and dangling guidelines reference) plus the newly discovered unlinked local spec file create a high probability that the agent will produce tasks with weak domain grounding. Specifically: the tech scoping document exists locally and is not referenced, which means the fix for issue 1 is literally one line change. Running the prompt as-is risks a full re-run after discovering the agent hallucinated the spec. Apply changes 1-2 above (5 minutes of edits) before running. Changes 3-4 are high-value but the prompt can run without them.