Session: serene-prancing-meadow-subagent-a7fc4a87 — 2026-03-05

Project: doctolib-doctolib · Branch: master · Mode: ` · **Model:**claude-sonnet-4-6`

Stats: 1 user messages, 8 tool calls, tools used: Read, Glob, Bash.

Conversation

Turn 1 — User

Please review the following prompt against prompt engineering best practices and provide actionable feedback for improvement.

This is a revised version of a prompt that was previously scored 3/5. The main changes from the previous version were: - Changed "1-3 max effort" to "1-3 days max effort" (clearer sizing) - Added a Figma fallback: "If Figma is not accessible, read the basic designs at [local PNG files]" - Consolidated the 3 duplicate "pre-write findings" steps into a single step 8 - Removed double slash bug in the oxygen path (though it still has @//Users/... — check this) - The step numbering went from 11 steps to 9 steps

PROMPT TO REVIEW:

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. 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. 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. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tasks.md until the pre-write findings are saved. After it, the research phase is complete. 9. Plan and create the tasks into the file @tmp/nhr-document-list/nhr-document-list-tasks.md.

Context about this prompt: - It is sent to Claude Code (an AI coding assistant) to generate JIRA-ready task breakdowns - The project is a large-scale Rails+TypeScript monorepo …(truncated, 1299 more chars)

Turn 1 — Assistant

I'll review the prompt systematically against the 5 criteria, incorporating the specific evaluation points you've raised.

Tools used:

• Read: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list

Tool results:

→ result (ERROR): EISDIR: illegal operation on a directory, read '/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list'

Tools used:

• Read: /Users/USER/workspace/doctolib/doctolib/CLAUDE.md

Tool results:

→ result (ERROR): <tool_use_error>Sibling tool call errored</tool_use_error>

Tools used:

• Glob: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/**/*

Tools used:

• Glob: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/**/*

Tool results:

→ result (ok): /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/Documentation_eSanteConnect-JSON-2.1.0_EN.md /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/DMP certification.xlsx /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/entry-point.png /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/NHR Document List.png /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/pre-write-findings.md /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/ …(truncated, 1709 more chars)

Tool results:

→ result (ok): /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/CODEOWNERS.local /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/babel.config.cjs /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/catalog-info.yaml /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/jest.config.cjs /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/sonar-project.properties /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/dmp/tsconfig.json /Users/USER/wor …(truncated, 10052 more chars)

Tools used:

• Read: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/pre-write-findings.md (1–60)

Tool results:

→ result (ok): 1→# Pre-Write Findings — NHR Document Viewer 2→ 3→## Selected Oxygen Components 4→ 5→| Component | Import | Why selected | 6→|---|---|---| 7→| Modal | @doctolib/design-system/Modal | Full-screen document list container; show/onHide props match open-state control pattern | 8→| Table | @doctolib/design-system/Table | Native loading + skeletonLoaderProps avoid custom skeleton code | 9→| TableHead, TableBody, TableRow, TableCell, `Table …(truncated, 4871 more chars)

Tools used:

• Glob: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/**/*.ts

Tool results:

→ result (ok): /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/hooks/useNationalHealthRecords.ts /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/index.ts

Good. I have enough context to do a thorough review. Let me also check the oxygen path issue specifically.

Tools used:

• Bash: ls /Users/USER/workspace/doctolib/oxygen 2>&1 | head -5

Tools used:

• Read: /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tech-scoping.md (1–30)

Tool results:

→ result (ok): 1→# NHR Document Viewer — Tech Scoping 2→ 3→--- 4→ 5→# Who? 6→ 7→- Team: FIRE 8→- Tech holder: @[someone] 9→- Product manager: @[someone] 10→- Product Security: @[product-security-reviewer] 11→- Reviewers: @[your-em], @[a-staff-engineer], @[someone-in-your-team] 12→ 13→MMO 14→ 15→| | | 16→|---|---| 17→| In an engine | yes | 18→| Engine name | tpf-national-health-records-ui |

…(truncated, 966 more chars)

Tool results:

→ result (ok): agents CLAUDE.md CODEOWNERS commitlint.config.ts eslint.config.js

I now have enough information to deliver a thorough, grounded review.

PROMPT SCORE: 3/5

QUICK ASSESSMENT:

• Context & Role: ✅ - Clear Staff Engineer persona with domain context (NHR/DMP, Doctolib, Junior audience)
• Structure: ⚠️ - Steps are sequential and logical but two sections ("Output Format" and "Suggested actions") carry overlapping instructions that create an enforcement ambiguity
• Examples: ❌ - No example of a well-formed output task is provided; the template description is prose-only
• Reasoning: ⚠️ - Step 8 enforces a pre-write gate but there is no instruction to reason about task sizing, dependency risk, or which package a task belongs to before writing
• Control: ⚠️ - Output verbosity per task section is under-constrained; "at minimum explain" leaves wide variance in what a Junior gets

REMAINING ISSUES BY SEVERITY:

CRITICAL

1. Confluence URL has no fallback and requires authenticated access. The agent cannot read https://doctolib.atlassian.net/... without a session cookie. Unlike the Figma fallback, there is no local copy offered. The tech scoping file already exists at /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tech-scoping.md (and a v2 variant). The prompt should point to that file as the primary source and treat the URL as secondary.

Diff:

-1. Read the Tech Scoping from https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View from the Doctolib's confluence page.
+1. Read the Tech Scoping from @/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-document-list-tech-scoping.md (and the v2 proposal at nhr-document-list-tech-scoping-proposal-v2.md). The Confluence URL https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View is a reference only — it requires authentication and cannot be fetched.

2. Double slash in the oxygen path is still present. Step 7 reads @//Users/USER/workspace/doctolib/oxygen. The correct path confirmed on disk is /Users/USER/workspace/doctolib/oxygen. In Claude Code the @ prefix followed by a path resolves the path literally, so @//Users/... becomes //Users/... which is not a valid absolute path on macOS.

Diff:

-7. Read the oxygen code base from @//Users/USER/workspace/doctolib/oxygen
+7. Read the oxygen code base from @/Users/USER/workspace/doctolib/oxygen

MAJOR

3. "Doctolib development guidelines" is still a dangling reference. The opening paragraph says "according with Doctolib development guidelines" but never links to CLAUDE.md, a style guide, or any concrete rule. Because the agent has access to /Users/USER/workspace/doctolib/doctolib/CLAUDE.md, this should be made explicit.

Diff:

-...tasks to be implemented according with Doctolib development guidelines...
+...tasks implemented according with the project guidelines at @/Users/USER/workspace/doctolib/doctolib/CLAUDE.md (TypeScript mandatory, React Query v5, background migrations, engine API boundaries, etc.)...

4. No example of a complete output task. The output format section describes fields in prose but gives no concrete specimen. Without one, different runs produce wildly inconsistent levels of detail in "Description/Objective" and "Acceptance criteria." A single inline example — even 15 lines — anchors the expected depth far more reliably than the current prose description. At minimum, add a skeleton showing how the code snippet and mocked data fields look inside the markdown.

Example addition at the end of the Output Format section:

### Example task shape (do not include this in the output):

## Task 1 — Feature Switch: nhr_document_list

**Description/Objective**
Adds the `nhr_document_list` feature switch to control visibility of the NHR entry point.
Fits into the project as the mandatory gate for all subsequent tasks.
Target file: `engines/feature_switches/app/public/feature_switches/api/feature_switch_list.rb`

```ruby
# implementation reference
FeatureSwitches::Api::FeatureSwitchList.register(:nhr_document_list, default: false)

Acceptance Criteria - [ ] Unit test: feature switch is off by default - [ ] Placement: inside engines/feature_switches/ - [ ] Staging test: toggle on in Flipper UI, confirm entry point renders; toggle off, confirm it is hidden

Dependencies - Parent tasks: none - Child tasks: Task 2 (NHR Entry Point)

**5. The entry point PNG filename referenced in the Figma fallback does not match what is on disk.**
The prompt references `@/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/nhr-list-entry-point.png` but the file on disk is `entry-point.png`, not `nhr-list-entry-point.png`. This will silently fail if Figma is unreachable.

Diff:
```diff
-...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
+...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/entry-point.png

MINOR

6. No instruction to reason about which package each task belongs to before writing. The pre-write findings gate (step 8) enforces research but does not ask the agent to explicitly decide package placement per task before writing. Given the pre-write findings already discovered a package coupling violation (Author type), a one-line addition to step 8 would prevent that class of error from propagating into the task descriptions.

Addition to step 8:

+For each planned task, record in the findings: which package/folder it targets, and whether it requires a new file or modifies an existing one.

7. "Other tasks" in the constraint ordering is under-specified. The constraint says tasks 1-3 have a fixed order and then "4. Other tasks." It is unclear whether the "other tasks" must also be topologically ordered by dependency, or whether they can be written in any sequence. Clarify:

-4. Other tasks
+4. Remaining tasks — ordered by dependency (each task's parent must appear before it in the list)

SUMMARY OF CHANGES MADE VS. REMAINING: