Project: doctolib-doctolib · Branch: master · Mode: · Model: claude-sonnet-4-6 Stats: 1 user messages, 0 tool calls, tools used: none. Conversation Turn 1 — User Please review the following prompt against prompt engineering best practices and provide actionable feedback for improvement: --- 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 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. Other tasks 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. 3. Pre-write findings on @tmp/nhr-document-list/nhr-document-list-tasks-findings.md. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tasks.md until the pre-write findings are saved. 4. Read the code base from @/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp 5. Read the code base from @/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records 6. Read the code base from @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records 7. Read the code base from @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui 8. Pre-write findings on @tmp/nhr-document-list/nhr-document-list-tasks-findings.md. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tasks.md until the pre-write findings are saved. 9. Read the oxygen code base from @//Users/USER/workspace/doctolib/oxygen 10. Pre-write findings on @tmp/nhr-document-list/nhr-document-list-tasks-findings.md. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tasks.md until the pre-write findings are saved. 11. Plan and create the tasks into the file @tmp/nhr-document-list/nhr-document-list-tasks.md. --- Context about this prompt: - It will be given to Claude Code (an AI coding assistant) to generate JIRA-ready task breakdowns - The project is a large-scale Rails+TypeScript monorepo at Doctolib - Relevant codebases: packages/@doctolib/dmp, packages/@doctolib/national-health-records, treatment-plan packages (tpf-national-health-records, tpf-national-health-records-ui), and oxygen design system - "NHR" = National Health Records (French: DMP - Dossier Médical Partagé) - Tasks should be sized for Junior Developers with 1-3 story points max each - The "Suggested actions" section describes a sequen …(truncated, 526 more chars) Turn 1 — Assistant PROMPT SCORE: 3/5 QUICK ASSESSMENT: - Context & Role: - Role is defined but mixes seniority (Staff Engineer) with execution (Junior sizing) without clarifying the agent's own behavior constraints - Structure: - Steps 3/8/10 duplicate the same instruction ("pre-write findings, don't write tasks.md yet") creating noise; constraint ordering logic is buried mid-prompt - Examples: - No example task provided; junior developers sizing "1-3 max effort" is ambiguous (story points? hours? days?) - Reasoning: - No request for the agent to reason about why a task is sized a certain way or how it maps to the scoping document - Control: - Output format is detailed but "at minimum explain" is vague; no cap on task count; no instruction on what to do if URLs are inaccessible TOP 3 IMPROVEMENTS: 1. Disambiguate "1-3 max effort" and add a task count boundary. Current: "divide the implementation in tasks... in between 1-3 max effort" Fix: "Break down the implementation into tasks, each sized 1-3 story points (using Fibonacci: 1=trivial/half-day, 2=1 day, 3=2 days for a junior developer). Target 8-15 tasks total." 2. Add a fallback instruction for inaccessible URLs (Confluence, Figma) to prevent silent failure. Current: "Read the Tech Scoping from https://..." Fix: "Read the Tech Scoping from https://... . If the URL is inaccessible, stop immediately and report the error to the user before proceeding. Do not fabricate scoping details." 3. Consolidate the 3 duplicate "pre-write findings" instructions into a single phased workflow with clear gate conditions. Current: Steps 3, 8, 10 each repeat "Pre-write findings... Do not write anything on tasks.md until..." Fix: Restructure as two explicit phases: - Phase 1 (Research): Steps 1-6, append all findings to findings.md after EACH step - Phase 2 (Write tasks): Only begin after explicitly stating "All research complete. Beginning task generation." in findings.md IMPROVED VERSION (score was 3/5 with multiple structural issues warranting a rewrite): --- You are a Staff Frontend Software Engineer at Doctolib. Your goal is to break down a feature scoping document into JIRA-ready tasks sized for Junior Software Developers (1-3 story points each, where 1=half-day, 2=1 day, 3=2 days). Sizing reference: - 1 point: Single file change, clear pattern to follow, no new abstractions - 2 points: Multiple files, requires reading existing code, minor design decisions - 3 points: Cross-package changes, requires understanding domain context, non-trivial logic Required task ordering (hard constraints): 1. Feature switch implementation (no dependencies) 2. Create the NHR Entry Point (depends on task 1) 3. Open the NHR Document List Modal as empty full-size modal (depends on task 2) 4. All remaining tasks (ordered by dependency, no single task may exceed 3 points) Partial implementation rule: Tasks may intentionally defer work. Example: "Open the NHR Document List Modal" renders an empty modal only. Table, data, filters, and columns are separate subsequent tasks. Always state explicitly in a task what is deferred and to which future task. Output files: - Research: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tasks-findings.md - Final tasks: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tasks.md --- PHASE 1: Research (complete fully before writing tasks.md) Execute each step sequentially. After each step, append findings to findings.md before proceeding. If any URL is inaccessible, stop and report to the user immediately. Step 1: Read the Tech Scoping at https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View Step 2: Read the Figma design at https://www.figma.com/design/D5jfoP7Ed1teAOvL0yH2gV/%F0%9F%87%AB%F0%9F%87%B7--MOOSE--DMP-Segur-V2-2026?node-id=3187-100822 Step 3: Read the codebase at /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp Step 4: Read the codebase at /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records Step 5: Read the codebase at /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records Step 6: Read the codebase at /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui Step 7: Read the Oxygen design system at /Users/USER/workspace/doctolib/oxygen After Step 7, write "RESEARCH COMPLETE" as the last line of findings.md before starting Phase 2. --- PHASE 2: Write tasks.md Only begin after findings.md ends with "RESEARCH COMPLETE". Each task must follow this exact structure: markdown Task N: [Title] Story Points: [1 | 2 | 3] Dependencies: [Task numbers that must be completed first, or "None"] Dependents: [Task numbers that depend on this task, or "None"] Objective [2-4 sentences: what is being implemented, how it fits the overall NHR List View feature, and what is explicitly deferred to a later task.] Target Files - path/to/file.tsx — [reason this file is touched] Implementation Reference [Code snippet showing the pattern to follow, with mocked data where applicable. Must reference existing patterns from the read codebases.] Acceptance Criteria - [ ] Unit test: [specific behavior to test] - [ ] Package/folder placement: [exact path, e.g., packages/@doctolib/national-health-records/src/components/] - [ ] Staging verification: [exact steps to verify on staging, e.g., "Enable feature switch X, navigate to patient Y, verify modal opens"] Target 8-15 tasks total. If the scoping requires more, flag it explicitly and ask the user before proceeding. --- Additional structural issues worth noting: The step 9 path contains a double slash (@//Users/...) which will cause a file read failure. The corrected path should be /Users/USER/workspace/doctolib/oxygen. This is a concrete bug in the original prompt. The phrase "Doctolib development guidelines" in the original is a dangling reference — the agent has no way to look these up without a path. The improved version implicitly grounds this by requiring code patterns to be sourced from the read codebases. If there is a CLAUDE.md or guidelines document, add an explicit read step for it.