Project: doctolib-tmp · Branch: master · Mode: ` · **Model:**claude-sonnet-4-6`
Stats: 1 user messages, 9 tool calls, tools used: Read, Glob.
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.
You are a Staff Frontend Software Engineer at Docolib 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 Risks identified in Discovery and Remediation plan - Features break down in Stories - Security: Product Security's analysis - Architecture - Proposed solution - Data flow - Feature flags - How scale to include new countries - Risks - 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@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
Please provide: 1. An overall assessment of the prompt quality 2. Specific issues found (clarity, structure, completeness, ambiguities) 3. Actionable suggestions for improvement 4. A revised version of the prompt that addresses all issues found
Additional context about the codebase that may be useful for your review:
- This is a React/TypeScript monorepo at Doctolib
- CLAUDE.md requires: React Query v5 (v4 deprecated), TypeScript mandatory, functional components only, no eslint-disable comments
- The tpf-national-health-records package contains business types and service layer for NHR
- The tpf-national-health-records-ui package is where all UI components must live
- variation-management with useProductLineVariation is the internal pattern for country-specific code variations
- The DMP (Dossier Médical Partagé) is France's national health record system
- The project must be architected to support other countries' NHR systems in the future
Turn 1 — Assistant
I'll review this prompt systematically against the 5 key criteria before providing the revised version.
Tools used:
Read:/Users/USER/workspace/doctolib/doctolib/tmp
Tool results:
→ result (ERROR): EISDIR: illegal operation on a directory, read '/Users/USER/workspace/doctolib/doctolib/tmp'
Tools used:
Glob:/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records*/**/*
Tool results:
→ result (ERROR): <tool_use_error>Sibling tool call errored</tool_use_error>
Tools used:
Glob:/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records*/**/*.ts
Tools used:
Glob:/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list*
Tool results:
→ result (ok): No files found
Tool results:
→ result (ok): /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-plan.md /Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-tech-scoping.md
Tools used:
Glob:/Users/USER/workspace/doctolib/treatment-plan/packages/**
Tools used:
Read:/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-tech-scoping.md(1–50)
Tool results:
→ result (ok): 1→ 6→ 7→This document is a snapshot of the added value of your project, so it should be updated all along the development cycle: if the technical specifications change during your dev, this document should reflect (and explain) the new technical choices. Please read …(truncated, 2638 more chars)
Tool results:
→ result (ok): /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-medication-database-sdk/.npmignore /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-medication-database-sdk/bin/migrate_to_rq_v5.sh /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-medication-database-sdk/orval.config.ts /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-medication-database-sdk/src/orval/queryOptions.ts /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-muster-forms/.npmignore /Users/U …(truncated, 10767 more chars)
Tools used:
Read:/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-tech-scoping.md(50–250)
Tool results:
→ result (ok): 50→--- 51→ 52→# When? 53→ 54→- Dev start date: TBD 55→- Dev end date: TBD 56→- Estimated DevM: TBD 57→ 58→--- 59→ 60→# Summary 61→ 62→### In the scope 63→ 64→Enable healthcare professionals (HCPs) to browse a patient's DMP (Dossier Médical Partagé / "Mon Espace Santé") documents directly from Doctolib's EHR interface. 65→ 66→This scoping covers DMP 3.1 and DMP 3.1a certification requirements only:
…(truncated, 17904 more chars)
I now have enough context to provide a thorough review. Let me also check the existing plan file for additional context.
Tools used:
Read:/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-plan.md
Tool results:
→ result (ERROR): File content (35679 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content.
Tools used:
Read:/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-plan.md(1–80)
Tool results:
→ result (ok): 1→# NHR Document List — Implementation Plan 2→## Scope: DMP 3.1 + DMP 3.1a only (DMP 3.2 and 3.3 deferred to a separate project) 3→ 4→--- 5→ 6→## Context 7→ 8→France's DMP (Dossier Médical Partagé / "Mon Espace Santé") is the national shared health record. 9→Healthcare professionals need to browse a patient's DMP documents directly from Doctolib. 10→ 11→This plan is scoped to the DMP 3.1 and 3.1a certification requirements from the DMP certific …(truncated, 5338 more chars)
I have enough information to produce a thorough and accurate review. Here it is.
PROMPT SCORE: 2/5
QUICK ASSESSMENT:
- Context & Role: ⚠️ - Role is named "Docolib" (typo for "Doctolib") and lacks seniority signal; no behavioral guidelines (e.g. "prioritize certification compliance over elegance") are given.
- Structure: ⚠️ - Output sections are listed but not ordered or numbered; the AI cannot tell which sections must be completed before others, and the relationship between functional requirements and architecture is not spelled out.
- Examples: ❌ - No examples of desired section content, depth level, or formatting conventions are provided; the AI has no signal for how much detail is expected per story, risk, or architecture diagram.
- Reasoning: ❌ - No chain-of-thought directive; the prompt does not ask the AI to reason through trade-offs, validate constraints against requirements, or flag contradictions before writing.
- Control: ⚠️ - Output format is partially defined but verbosity per section is uncontrolled; no word/depth budget per section; the Risks section is listed twice in the output format spec (a copy-paste error).
TOP 3 IMPROVEMENTS:
-
Add a step-by-step reasoning directive before writing. Without it, the AI jumps straight to drafting and misses contradictions (e.g. the product spec calls for a pre-fetch on record open but the call-discipline rule EX_3.1-2030 forbids it — this conflict must be surfaced before any architecture section is written). Add: "Before writing any section, list all constraints and flag any contradictions between requirements, certification rules, and architectural constraints. Present these for review before proceeding."
-
Specify depth and quality bar per section, with a concrete example. "Features break down in Stories" is completely underspecified — the AI does not know if you want one-liner titles or full Given/When/Then acceptance criteria. Add a small example per section type, e.g.:
## Story example format
### FHIR-XXXX: [Short title]
**As a** healthcare professional, **I want** [...] **so that** [...].
**Acceptance Criteria:**
- EX_3.1-XXXX: [Certification rule this story satisfies]
- [Observable behavior]
Similarly for Risk rows: specify columns (Risk, Impact, Likelihood, Mitigation, Owner).
- Fix structural ambiguities before they corrupt the output. Three concrete fixes needed: (a) "Docolib" typo in the role definition must be corrected to "Doctolib" — it signals low-quality context to the model; (b) "Risks" is listed twice in the output format (once after "Features", once after "Architecture") — deduplicate and clarify that the Risks section is a single table that appears once; (c) the architectural constraint paths use inconsistent notation —
@tmp/...and@/Users/...mixed with@packages/...— standardize all paths to absolute filesystem paths to avoid ambiguity.
REVISED PROMPT:
You are a Staff Frontend Software Engineer at Doctolib. Your role is to produce a
production-quality Tech Scoping document for a feature that is certification-critical
(CNDA Ségur DMP audit). Prioritize correctness of certification requirements over
elegance. All code references must use the Doctolib development guidelines (React 18,
TypeScript mandatory, React Query v5, functional components only, no eslint-disable
comments, useProductLineVariation for country variation).
---
## Step 1 — Reason before writing (mandatory, show output before proceeding)
Before drafting any section:
1. List every hard constraint from the sources below (certification rules, architectural
boundaries, codebase conventions).
2. Identify any contradictions between sources (e.g. product spec vs. certification rule
vs. architectural constraint). Flag each with a proposed resolution.
3. Identify the 3 highest-risk unknowns that could block implementation.
4. Only after presenting this analysis, proceed to Step 2.
---
## Step 2 — Write the Tech Scoping document
Write the document to:
/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list-tech-scoping.md
Use the following section order. Do not deviate from it.
### Required sections (in order)
1. **Summary** — 3–5 sentences: what is being built, why it is urgent (certification
deadline), and what is explicitly deferred.
2. **Scope table** — Two-column markdown table:
| In scope | Out of scope |
Each row is one distinct feature or certification requirement.
3. **Risks table** — Four-column markdown table:
| Risk | Impact | Likelihood | Remediation |
Cover at minimum: DMP call-discipline rate limit, upstream FHIR-2001 dependency,
parallel adapter naming alignment with FHIR-2049–2052.
4. **Feature breakdown into Stories** — One subsection per story.
Each story must follow this exact format:
### [Story title] As a [role], I want [action] so that [outcome]. Certification rules satisfied: [EX_3.1-XXXX / RG_XXXX list] Acceptance criteria: - [ ] [Observable, testable criterion]
5. **Security** — Product Security analysis: data in transit, patient data exposure
surface, DMP access <REDACTED>, feature flag kill switch.
6. **Architecture**
- 6a. Proposed solution: describe the three-layer design
(generic renderer / variation hook / country adapter).
- 6b. Data flow: describe the request lifecycle from modal open to rendered list,
including the two-state filter pattern and React Query caching strategy.
- 6c. Feature flags: name, cohort type, expiry, frontend constant.
- 6d. How to add a new country: step-by-step (what to add in
`@doctolib/national-health-records`, what the new variant must implement,
how `useProductLineVariation` enforces exhaustive coverage at build time).
7. **Testing strategy** — Unit, integration, and certification verification checklist.
Specify which framework (Jest + React Testing Library), what must be mocked
(DmpNhrAdapter), and the certification verification checklist items that must pass
before go-live.
8. **Open questions** — Numbered list. Each item must include: the question, who owns
the answer, and the deadline impact if unresolved.
---
## Functional requirements
- Product requirements for DMP (France):
https://doctolib.atlassian.net/wiki/spaces/PTA/pages/3810591019/FIRE+-+DMP+List+View+Draft
- DMP certification rules spreadsheet:
/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/DMP certification.xlsx
(sheets: "All Reqs. DMP", "RG", "TD")
- DMP official API documentation:
/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/Documentation_eSanteConnect-JSON-2.1.0_EN.md
## Design references
- Entry point mockup:
/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/entry-point.png
- NHR Document List mockup:
/Users/USER/workspace/doctolib/doctolib/tmp/nhr-document-list/NHR Document List.png
---
## Architectural constraints (hard rules, do not deviate)
1. All UI components must live in:
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui
2. UI components must consume only services and types exported from:
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records
Do not reach into internal package internals.
3. Country-specific logic (filters, column renderers, data hooks) must be injected as
props/config and must NOT be imported directly inside the UI package.
4. All country-specific code (France DMP filters, columns, data hook) must live in:
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records
and must use `useProductLineVariation` from `@doctolib/variation_management`.
5. TypeScript: no `any`, no eslint-disable, no React Query v4 (`useQuery` from
`react-query` is forbidden — use `@tanstack/react-query` v5 only).
---
## Codebase conventions to enforce throughout the document
- Functional components only (no class co
…(truncated, 1532 more chars)