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 review and improve a project plan. The improvement must use the Doctolib development guidelines and must be scalable for other countries. The output must be a new Mardown document at @tmp/nhr-document-list/nhr-document-list-tech-scoping-v2.md only with the proposed changes.
Read the NHR List view tech scoping present on Confluence at https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3813048976/NHR+List+View and add the implementation requirement: - Inside @packages/@doctolib/national-health-records/ folder must have a components folder that will be reusable for different countries (e.g ePA and DMP) - The reusable components are Filters and Columns definitions to be included into the NhrDocumentListVariant - Add implementation examples for two FilterConfig and two ColumnConfig to be added to the final document. - Create the filters UI components example based on the Design from @tmp/nhr-document-list/NHR Document List-v2-filtering.png - Create the columns UI components example based on the Design from the NHR Document View from @tmp/nhr-document-list/NHR Document List-v2-basic.png
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 Filter design UI from @tmp/nhr-document-list/NHR Document List-v2-filtering.png 3. Read the Columns design UI from @tmp/nhr-document-list/NHR Document List-v2-basic.png 4. Propose a strategy on how to create a shared folder inside @packages/@doctolib/national-health-records/ to contain configurable components for the filters and columns and add them to the specific NhrDocumentListVariant. 5. Pre-write findings on @tmp/nhr-document-list/nhr-document-list-tech-scoping-proposal-v2.md. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tech-scoping-v2.md until the pre-write findings are saved. 6. Find the oxygen components necessary to implement the filters and columns: @/Users/USER/workspace/doctolib/oxygen and append to the pre-write findings on @tmp/nhr-document-list/nhr-document-list-tech-scoping-proposal-v2.md listing the ones to be used for the project based on the Filter UI and Columns UI design. Do not write anything on @tmp/nhr-document-list/nhr-document-list-tech-scoping-v2.md until the pre-write findings are saved. 7. Create a diagram explaning the dependencies between oxygen, the shared folders and the NhrDocumentListVariant. Append to the pre-write findings on @tmp/nhr-document-list/nhr-document-list-tech-scoping-proposal-v2.md 8. Create the @tmp/nhr-document-list/nhr-document-list-tech-scoping-v2.md explaining how the shared components architecture will be inserted into the Tech Scoping
Context about the codebase:
- This is a large Rails + TypeScript monorepo for Doctolib
- The package @doctolib/national-health-records is at packages/@doctolib/national-health-records/
- Oxygen is the design system at /Users/USER/workspace/doctolib/oxygen
- NhrDocumentListVariant is a country-specific variant component
- The prompt is intended to be used as a Claude Code prompt (slash command or agent prompt)
Turn 1 — Assistant
I'll review this prompt against prompt engineering best practices.
PROMPT SCORE: 3/5
QUICK ASSESSMENT:
- Context & Role: ✅ - Clear role as Staff Frontend Engineer with domain context
- Structure: ✅ - Numbered action steps are clear and sequential with a pre-write safeguard
- Examples: ⚠️ - Requirements mention "two FilterConfig and two ColumnConfig examples" but no template or schema is shown
- Reasoning: ❌ - No request for reasoning or intermediate decisions; agent is expected to act without explaining tradeoffs
- Control: ⚠️ - Output format is partially defined (Markdown doc) but verbosity, section structure, and quality criteria are unspecified
TOP 3 IMPROVEMENTS:
1. Add explicit reasoning checkpoints between high-cost steps.
Steps 4 and 8 make major architectural decisions silently. Insert: "Before proceeding to step 5, explain your proposed
architecture and the tradeoffs vs alternatives (e.g. hooks vs render props, config objects vs HOCs). Wait for
confirmation." This prevents the agent from spending tokens on a wrong direction.
2. Define the expected schema/interface for FilterConfig and ColumnConfig before asking for examples.
The prompt asks for implementation examples without showing what shape they should take. Add a constraint block:
"FilterConfig must conform to the existing NhrDocumentListVariant props interface. If no interface exists, propose one
first and describe the fields (id, label, type, options, defaultValue) before writing examples."
3. Specify the required sections and scope of the final output document.
Step 8 says "create the document" without defining what belongs in it. Add: "The final document must include:
(1) Architecture diagram, (2) Shared component API contracts, (3) Two FilterConfig examples with TypeScript types,
(4) Two ColumnConfig examples with TypeScript types, (5) Migration path for existing ePA/DMP variants. Keep each
section under 300 words."
Additional notes on specific issues in the prompt:
Ambiguous scope in step 6. "Find the oxygen components necessary" is open-ended and will cause the agent to do
unbounded exploration of /Users/USER/workspace/doctolib/oxygen. Narrow it: "Search only under
/Users/USER/workspace/doctolib/oxygen/packages/ for components matching filter input types (Select, DatePicker,
Checkbox) and table/column primitives (Table, DataGrid). List each with its import path."
Step 7 diagram instruction is vague. "Create a diagram" without specifying format will produce inconsistent results.
Specify: "Create a Mermaid diagram (graph TD) showing the dependency chain from Oxygen primitives to shared
FilterConfig/ColumnConfig components to NhrDocumentListVariant."
The pre-write gate in step 5 is good but fragile. The instruction "Do not write anything on [...]-v2.md until..."
is repeated twice but could still be violated by a long-running agent. Strengthen it: "IMPORTANT: Steps 1-7 all write
exclusively to nhr-document-list-tech-scoping-proposal-v2.md. Step 8 is the ONLY step that writes to
nhr-document-list-tech-scoping-v2.md. Never write to the v2 file before step 8."
The Confluence URL will fail silently. Claude Code cannot fetch URLs during tool execution unless a browser/fetch
tool is available. The prompt should acknowledge this: "If the Confluence page is not accessible, read the cached
version at tmp/nhr-document-list/nhr-document-list-tech-scoping-v1.md as a fallback."
Relevant files for context if you want to further improve this prompt:
- /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/ - package structure
- /Users/USER/workspace/doctolib/oxygen - design system components