Session: binary-dancing-planet-subagent-a156a827 — 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 wants to use this prompt to have an AI plan and write a Tech Scoping document for a National Health Record Document Viewer React component at Doctolib.

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: table constaining the ones identified another column with Remediation plan - Features: break down the implementation into an ordered list of single implementation tasks that can be done between 1-3 days by a Junior Software Engineer at Doctolib - Security: Product Security's analysis - Architecture - Proposed solution - Data flow - Feature flags - How scale to include new countries - Testing strategy - Open question

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

Design: - Entry point for the showing the NHR Document list: @tmp/nhr-document-list/entry-point.png - NHR Document List: @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 @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
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 @packages/@doctolib/national-health-records
8. Create the implementation plan on markdown format.

Please provide: 1. An overall assessment of the prompt quality (score out of 5) 2. Specific issues found (clarity, structure, completeness, ambiguities) 3. Top improvements needed 4. A revised version of the prompt that addresses all issues

Additional context about the codebase that may be useful for your review: - This is a React/TypeScript monorepo at Doctolib - CLAUDE.md codebase rules: React Query v5 (v4 deprecated), TypeScript mandatory, functional components only, kebab-case files, PascalCase components, no eslint-disable comments - tpf-national-health-records package: business types and service layer for NHR - tpf-national-health-records-ui package: where all UI components must live - variation-management with useProductLineVariation is the internal Doctolib pattern for country-specific code variations - DMP = Dossier Médical Partagé, France's national …(truncated, 538 more chars)

Turn 1 — Assistant

PROMPT SCORE: 2/5

QUICK ASSESSMENT: - Context & Role: ⚠️ - Role is defined but lacks behavioral constraints (e.g., "think like a staff engineer, challenge assumptions, flag unknowns") - Structure: ⚠️ - Actions are numbered but the gap between reading inputs and producing outputs is under-specified; no quality bar per section - Examples: ❌ - No examples of expected depth, section length, or what a "good" scoping looks like - Reasoning: ❌ - No explicit gate requiring the model to reason before writing; it can jump straight to output without surfacing contradictions or open questions discovered during reading - Control: ⚠️ - Output format is listed but section depth, word count, and what "done" looks like are absent; "Open question" is singular but likely means plural

TOP 3 IMPROVEMENTS:

1. Add a mandatory reasoning gate before writing. Before producing any markdown, require the model to output a numbered "Discovery Notes" block listing contradictions, ambiguities, and gaps found across all inputs. This prevents shallow or hallucinated scoping content and surfaces real open questions. Example addition after Action 3: "Before proceeding to Action 4, produce a 'Discovery Notes' block: list every ambiguity, missing information, or conflict found across the requirements, design, and code. Do not write the scoping document until this block is approved or you have resolved each item."

2. Define a quality bar for each output section. The current format list is a table of contents, not a specification. Each section needs a minimum expectation. Example additions: "Risks: minimum 5 risks, each with likelihood (High/Med/Low), impact (High/Med/Low), and a concrete remediation step, not a generic one. Features: each task must name the file(s) to create or modify, the acceptance criterion, and which package it lives in. Architecture: the proposed solution must explicitly address how the generic component API avoids coupling to DMP-specific types, with a TypeScript interface sketch."

3. Fix path notation inconsistency and make architectural constraints unambiguous. The prompt mixes @tmp/, @/Users/..., and @packages/ notations with no explanation of what @ means in each context. A junior engineer reading this scoping will be confused. Replace all paths with explicit absolute or repo-relative paths and add a "Path Conventions" section at the top clarifying each prefix. Also make the constraint explicit: "The UI component must accept filters, columns, and data fetchers as typed props/injection points. It must not import anything from @packages/@doctolib/national-health-records directly."

REVISED PROMPT:

You are a Staff Frontend Software Engineer at Doctolib with deep expertise in React, TypeScript, 
and large-scale monorepo architecture. You think critically, challenge vague requirements, and 
surface risks before writing code or plans.

## Goal

Produce a Tech Scoping document for the National Health Record (NHR) Document Viewer React 
component. The document will be reviewed by engineering leads and used by Junior Engineers to 
implement the feature. It must be production-quality and certification-safe (CNDA Segur audit).

## Path Conventions

The following prefixes are used throughout this prompt:
- `treatment-plan://` = `/Users/USER/workspace/doctolib/treatment-plan/`
- `monolith://` = `/Users/USER/workspace/doctolib/doctolib/`
- All other paths are absolute filesystem paths.

## Inputs to Read

Read ALL of the following before writing anything:

1. Product requirements (DMP/France): https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3810591019/FIRE+-+DMP+List+View+Draft
2. DMP certification requirements: `/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/DMP certification.xlsx`
3. DMP official API documentation: `/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/Documentation_eSanteConnect-JSON-2.1.0_EN.md`
4. Entry point design: `/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/entry-point.png`
5. Document list design: `/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/NHR Document List.png`
6. Existing UI package: `treatment-plan://packages/tpf-national-health-records-ui/`
7. Existing service/types package: `treatment-plan://packages/tpf-national-health-records/`
8. Monolith-side NHR package: `monolith://packages/@doctolib/national-health-records/`

## Mandatory Reasoning Gate (Do Not Skip)

After reading all inputs and BEFORE writing the scoping document, produce a "Discovery Notes" 
block with:

- Contradictions found between product requirements, certification requirements, and the API docs
- Gaps in the design (e.g., states not shown in mockups: empty state, error state, loading state)
- Ambiguities in the architectural constraints
- Oxygen components identified as relevant (list component name and intended use)
- Where in the monolith engines the entry point belongs, and why
- Open questions that cannot be resolved from the inputs alone

Do not proceed to write the scoping document until the Discovery Notes block is complete.

## Architectural Constraints (Non-Negotiable)

1. All UI components must live in `treatment-plan://packages/tpf-national-health-records-ui/`. 
   No exceptions.
2. The UI component must consume types and service interfaces from 
   `treatment-plan://packages/tpf-national-health-records/` only. It must NOT import directly 
   from `monolith://packages/@doctolib/national-health-records/`.
3. The generic table/list component must expose a typed injection API (props or context) for: 
   filters, column renderers, and data fetchers. DMP-specific implementations of these must NOT 
   be imported inside the generic component.
4. All country-specific code (DMP filters, column renderers, data call) must live in 
   `monolith://packages/@doctolib/national-health-records/` and use `useProductLineVariation` 
   from `variation-management`.
5. No `eslint-disable` comments. TypeScript strict mode. React Query v5 only. Functional 
   components only. Kebab-case files, PascalCase components.

## Output: Tech Scoping Document

Write the document to: 
`/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-tech-scoping.md`

Use the following structure with the depth requirements specified for each section:

### 1. Summary (5-8 sentences)
What is being built, why it matters, which countries are in scope now vs. later, and the 
certification constraint.

### 2. Scope Table
Two-column table: "In Scope" and "Out of Scope". Minimum 6 rows each. Be specific.

### 3. Risks Table
Columns: Risk | Likelihood (H/M/L) | Impact (H/M/L) | Remediation Plan.
Minimum 6 risks. Remediation plans must be concrete and actionable, not generic.
Must include at least one certification/audit risk and one scalability risk.

### 4. Implementation Tasks
Ordered list of tasks executable by a Junior Software Engineer in 1-3 days each.
Each task must include:
- Task name
- Package/file(s) to create or modify (absolute path)
- Acceptance criterion (how you know it is done)
- Dependencies (which prior tasks must be complete)

Minimum 8 tasks. Group by phase: Phase 1 (foundation), Phase 2 (DMP implementation), 
Phase 3 (integration and entry point).

### 5. Security Analysis
Cover: data sensitivity (patient health records), auth/access control requirements, 
any FHIR or eSante-specific security constraints from the API docs, and frontend 
security considerations (no PII in logs, no caching of sensitive data in localStorage).

### 6. Architecture

#### 6a. Proposed Solution
Describe the component hierarchy with a TypeScript interface sketch for the injection API 
(filters, column renderers, data fetchers). Show how DMP plugs into the generic component 
without the generic component knowing about DMP.

#### 6b. Data Flow
Describe the full data flow from user action to rendered table row. Include: entry point 
trigger, service call, data transformation, rendering. A simple ASCII diagram is acceptab

…(truncated, 1492 more chars)