Session: binary-dancing-planet-subagent-ab922205 — 2026-02-27

Project: doctolib-tmp · 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 for quality, clarity, and prompt engineering best practices. The user is iterating on a prompt to have an AI plan and write a Tech Scoping document for a National Health Record Document Viewer React component at Doctolib. This is version 5 of the prompt after 4 previous reviews scoring 2/5, 2/5, 2/5, 3/5.

The key improvements made in v5 vs v4: - Added Action 8: Pre-write findings saved to a file before writing - Added Action 9: Pre-write at least 3 architectural diagrams before writing the document - Clarified that code acceptance criteria doesn't need to be listed (assumed known by developer) - Paths are now all absolute and consistent

THE PROMPT TO REVIEW:

You are a Staff Frontend Software Engineer at Doctolib and will plan a project. The product must use the Doctolib development guidelines and must be scalable for other countries.

Create a Tech Scoping for the implementation the National Health Record Document Viewer in markdown format, inside @tmp/nhr-document-list-tech-scoping.md

Output format Markdown file with: - Summary of the project - Scope: table containing features inside and outside the scope - Risks: Risks needs at least 6 rows with likelihood/impact/mitigation plan columns - Features: break down the implementation into an ordered list of single implementation tasks containing description/file paths/acceptance criterias to fulfill the function requirements that can be done between 1-3 days by a Junior Software Engineer at Doctolib. The code acceptance criteria does not need to be listed because it should be known already by the developer. - Security: Product Security's analysis - Architecture - Proposed solution - Data flow - Feature flags - How scale to include new countries - Testing strategy - Open questions

Functional requirements: - Product requirements for DMP (France): https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3810591019/FIRE+-+DMP+List+View+Draft - DMP certification requirements: @/Users/USER/workspace/doctolib/tmp/nhr-document-list/DMP certification.xlsx - DMP oficial API documentation: @/Users/USER/workspace/doctolib/tmp/nhr-document-list/Documentation_eSanteConnect-JSON-2.1.0_EN.md

Design: - Entry point for the showing the NHR Document list: @/Users/USER/workspace/doctolib/tmp/nhr-document-list/entry-point.png - NHR Document List: @/Users/USER/workspace/doctolib/tmp/nhr-document-list/NHR Document List.png

Architectural constraints: - All the UI code must be inside @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui folder - The UI must call the services and types defined in @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records - Country specific filters, column rendering and data calls must be injected and pass as parameter to the UI code. - All specific country code filters, columns and data call must be inside @/Users/USER/workspace/doctolib/packages/@doctolib/national-health-records and must use variation-management with useProductLineVariation

Actions:

1. Read all functional requirements
2. Read the proposed design
3. Read the referenced code at @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui, @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records
4. Find the place in the monolith codebase where the entry point must be.
5. Find the oxygen components necessary to implement the proposed design: @/Users/USER/workspace/doctolib/oxygen
6. Propose a strategy to on how to build a generic component to show the table using the types defined at @/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records and inject the filters, column rendering and service data call.
7. Propose the filters, columns rendering and data call for DMP. They must be inside @/Users/USER/workspace/doctolib/packages/@doctolib/national-health-records
8. Pre-write findings inside @/Users/USER/workspace/doctolib/t …(truncated, 1438 more chars)

Turn 1 — Assistant

PROMPT SCORE: 4/5

QUICK ASSESSMENT: - Context & Role: ✅ - Clear Staff Engineer role with Doctolib domain context - Structure: ✅ - 10 numbered actions, explicit output sections, constraints well-defined - Examples: ⚠️ - No example of what a "good" task breakdown looks like; format guidance is implicit - Reasoning: ✅ - Actions 8+9 establish a solid pre-write reasoning gate before final output - Control: ⚠️ - Output verbosity is uncontrolled; no guidance on task granularity or total document length

REASONING GATE ASSESSMENT (Actions 8 and 9):

Yes, the reasoning gate is adequately addressed. Action 8 forces the model to externalize intermediate findings (components, interfaces, conflicts) to a file before writing any section, preventing hallucinated architecture. Action 9 forces at least three concrete diagrams to be committed before the document body is written. Together these create a genuine "think before you write" checkpoint that mirrors how a staff engineer would draft a scoping document. This is the most important improvement from v4 and it works.

REMAINING GAPS:

1. No example of a well-scoped task breakdown. The instruction says tasks must be "1-3 days for a Junior Software Engineer" but gives no example of what a good task looks like (description + file path + acceptance criteria). Without a template or example, the model may produce tasks that are too coarse or too fine-grained.

Example to add under Features:

 Example task format:
 **Task: Create DocumentListTable component skeleton**
 - Description: Scaffold the generic table component accepting typed column definitions and row data
 - Files: `packages/tpf-national-health-records-ui/src/components/document-list-table/document-list-table.tsx`
 - Acceptance criteria: Renders empty state correctly; columns prop is typed against NHR types; passes TypeScript strict mode

2. Action 8 pre-write target is underspecified. "Pre-write findings inside the folder" does not say what file name or format to use, which may cause the model to pick an arbitrary structure or skip it under <REDACTED> Specify: "Save findings to @/Users/USER/workspace/doctolib/tmp/nhr-document-list/pre-write-findings.md with sections: Selected Components, Key Interfaces, Conflicts."

3. No constraint on document length or section depth. The output format lists 8 top-level sections with no length guidance. The model may produce a 5,000-word document or a 500-word stub. Add: "Each section should be comprehensive enough for a junior engineer to implement independently, targeting 3-5 paragraphs or equivalent structured content per major section."

REVISED VERSION:

A full rewrite is not warranted at 4/5. The targeted patch below addresses the three gaps above. Apply these additions to the existing prompt:

Under "Output format > Features", append:

  Example task format (use this structure for every task):
  **Task: [Task Name]**
  - Description: [What to build and why]
  - Files: [Absolute file paths to create or modify]
  - Acceptance criteria: [Observable behavior that proves correctness, excluding code style which is assumed]

Replace Action 8 with:

8. Pre-write findings to @/Users/USER/workspace/doctolib/tmp/nhr-document-list/pre-write-findings.md
   with the following sections before writing any section of the Tech Scoping:
   - Selected Oxygen Components (name + reason for selection)
   - Key TypeScript Interfaces (interface name + source file)
   - Conflicts or Gaps Found (description + proposed resolution)

After "Output format" block, add:

Length guidance: Each major section must be comprehensive enough for a junior engineer to act on independently.
Target 3-5 paragraphs or equivalent structured content (tables, diagrams, lists) per section.
The Features section must contain a minimum of 8 tasks and a maximum of 20 tasks.

SUMMARY:

The prompt has crossed the 4/5 threshold. The reasoning gate introduced in v5 is the right call and is implemented correctly. The remaining gaps are polish-level, not structural. The three additions above (task example, pre-write file spec, length guidance) would bring this to a solid 5/5 and meaningfully reduce variance in model output quality.