Skill: unfallenwill/dvp-composer (version 0.5.0)

--- name: dvp-composer description: > This skill should be used when the user asks to "compose DVP", "create a DVP", "Data Validation Plan", "data cleaning plan", "edit check spec", "validation check list", "write DVP", "draft DVP", or mentions creating, reviewing, or drafting a data validation plan or data cleaning strategy for clinical trials in CRO or sponsor data management contexts. version: 0.5.0 --- # DVP Composer ## Purpose Guide the user through a structured 6-phase interactive workflow to compose a Data Validation Plan (DVP) for clinical trial Data Management in CRO context. Each phase builds on the previous one, with user confirmation required between phases. ## Workflow Overview | Phase | Name | Goal | |-------|------|------| | 1 | Collection | Read protocol, CRF, SAP and other materials; understand study data context | | 2 | Scope & Strategy | Define validation scope, key variables, risk points, and check methods | | 3 | Design Checks | Design specific, executable check rules per module | | 4 | Alignment | Confirm rules are correct, feasible, and not conflicting | | 5 | Draft | Compile everything into a structured DVP document | | 6 | Internal Review | Review for completeness, consistency, and clarity | After completing each phase, present a summary to the user and ask for confirmation before proceeding to the next phase. If the user requests changes, iterate within the current phase before moving forward. ## Task Tracking When the workflow starts, create a task list to give the user a clear roadmap and granular progress tracking. ### Phase-Level Tasks At workflow startup, use `TaskCreate` to create 6 phase-level tasks in order. Each task must include `addBlockedBy` pointing to the previous phase's task ID (except Phase 1). Mark Phase 1 as `in_progress` immediately. | Phase | subject | description | activeForm | |-------|---------|-------------|------------| | 1 | Phase 1: Collection | Gather all input materials and understand study context | Collecting study materials | | 2 | Phase 2: Scope & Strategy | Define validation scope, key data, and risk points | Defining validation scope & strategy | | 3 | Phase 3: Design Checks | Design executable check rules per module | Designing check rules | | 4 | Phase 4: Alignment | Verify rules are correct, feasible, and conflict-free | Aligning check rules | | 5 | Phase 5: Draft | Compile DVP document and generate Excel output | Drafting DVP document | | 6 | Phase 6: Internal Review | Review for completeness, consistency, and clarity | Reviewing DVP internally | Example: ``` TaskCreate subject="Phase 1: Collection" description="Gather all input materials and understand study context" activeForm="Collecting study materials" → returns task_id (use the returned value, not a hardcoded number) TaskCreate subject="Phase 2: Scope & Strategy" description="Define validation scope, key data, and risk points" activeForm="Defining validation scope & strategy" addBlockedBy=[<Phase 1 task_id>] ...and so on for all 6 phases. TaskUpdate taskId=<Phase 1 task_id> status="in_progress" ``` ### Sub-Tasks When entering a phase, read its reference file and create sub-tasks for that phase's steps. Each sub-task should `addBlockedBy` the current phase's task ID. Mark each sub-task `completed` as its step finishes. When all sub-tasks are done, mark the phase-level task as `completed` and the next phase as `in_progress`. ### Dynamic Task Decomposition When a sub-task involves work across multiple distinct items whose count depends on runtime context, decompose it into leaf-level work items tracked with the task system. **When to decompose** — apply when a sub-task: - Involves iterating over a list whose length is determined at runtime (modules, dimensions, findings, materials) - Has distinct work items that can be completed independently - Risks losing progress or missing items without individual tracking **How to decompose**: 1. Before starting the sub-task's actual work, identify the items (e.g., read `data-modules.md` to get the module list) 2. Use `TaskCreate` to create one leaf task per item — each MUST `addBlockedBy` the parent sub-task's task ID 3. Set the first leaf task to `in_progress` 4. Complete each leaf task in order: mark `completed`, then set next `in_progress` 5. When all leaf tasks are `completed`, mark the parent sub-task as `completed` **Naming**: Leaf task subjects use the pattern `[Sub-task subject]: [item]`, e.g. `Design by Module: AE/SAE`. **When NOT to decompose** — skip decomposition when the sub-task has 2 or fewer items, or the items are trivial (single-action each). Use judgment — decomposition should help tracking, not add overhead. ### Phase Transition At each `[Done]` confirmation: 1. Mark the current phase task as `completed` 2. Mark the next phase task as `in_progress` 3. Load the next phase file and create its sub-tasks ## Input Methods Support three input methods simultaneously: 1. **Paste text**: User pastes protocol summaries, CRF descriptions, etc. directly into the conversation 2. **Read files**: User provides file paths (PDF, Word, Markdown); use the Read tool to access content 3. **Q&A**: Claude asks targeted questions, user answers verbally Adapt questioning strategy based on what the user has readily available. Do not demand all materials upfront — work with what is provided and ask targeted questions for gaps. ## Output Generate an Excel (.xlsx) file as the final DVP document. **Template handling**: If the user provides a DVP Excel template during Phase 1, use that template's format and sheet structure. Otherwise, generate with the default 4-sheet format (see `references/excel-spec.md`). **Default sheets**: - **Check List** — All validation rules (Check ID, module, description, logic, trigger, query wording, priority, method) - **Summary** — Document overview, scope, roles & responsibilities, review strategy - **Revision History** — Version change log - **Ext Data Recon** — External data reconciliation checks ## Workspace All phase deliverables are written to `dvp_workspace/` under the user's working directory. ### Rules 1. Create `dvp_workspace/` when the workflow starts 2. At each phase's [Done] step, write all deliverable files to `dvp_workspace/` 3. At the start of each phase (except Phase 1), read the previous phase's deliverable files first 4. File names are hard-coded in each phase instruction — do not rename them 5. Overwrite existing files without asking for confirmation 6. All files use Markdown format. The only exceptions are: `dvp_content.json` (JSON), `DVP_<ProtocolNumber>_v1.0.xlsx` (Excel), and any user-provided template files. ### Cross-Phase File: assumptions-and-gaps.md Phase 1 creates this file with the initial table structure: `| # | Category | Description | Status | Phase |`. Phases 2 and 3 MUST append new rows (with Status = Open) when they encounter information gaps or make assumptions not confirmed by the user. Phase 4 MUST update the Status column from Open to Resolved for each item it resolves. Before appending, MUST read the existing file to avoid duplicate entries. ## Phase Instructions For detailed instructions on each phase, load the corresponding reference file from the skill's `references/stages/` directory (relative to the skill root at `skills/dvp-composer/`): - **Phase 1**: `references/stages/phase-1-collection.md` - **Phase 2**: `references/stages/phase-2-strategy.md` - **Phase 3**: `references/stages/phase-3-design.md` - **Phase 4**: `references/stages/phase-4-alignment.md` - **Phase 5**: `references/stages/phase-5-draft.md` - **Phase 6**: `references/stages/phase-6-review.md` Load each phase file at the start of that phase. Do not load all phases upfront. After loading the phase file, read the previous phase's deliverable files from `dvp_workspace/` (except Phase 1, which has no predecessor). Each phase instruction lists exactly which files to read. ## Additional References - **`references/section-catalog.md`** — Standard DVP document structure. Load during Phase 5 to verify all required document sections are included. - **`references/excel-spec.md`** — Detailed Excel output format specification. Load during Phase 5 when generating output. - **`references/example-output.md`** — Example DVP output with sample check rules. Load during Phase 3 if the user wants to see examples. ## Script Use `scripts/generate_xlsx.py` to generate the final Excel file. The script accepts a JSON input containing all DVP content and produces the formatted .xlsx output. ```bash python3 scripts/generate_xlsx.py --input dvp_workspace/dvp_content.json --output dvp_workspace/DVP_<ProtocolNumber>_v1.0.xlsx [--template dvp_workspace/template.xlsx] ``` All file paths in the command MUST use the `dvp_workspace/` prefix. If the script exits with a non-zero code, read the error message, fix the JSON input, and re-run. MUST NOT proceed to the [Done] step until the script succeeds. ## Interaction Protocol All phases must follow this unified interaction protocol for when and how to ask the user questions. ### Decision Framework — When to Ask At each decision point, determine the appropriate level: | Level | Condition | Action | |-------|-----------|--------| | **Self-decide** | Answer is derivable from provided materials; follows industry convention; low-impact and correctable | Decide independently, record assumption | | **Recommend** | Reasonable default exists but multiple valid options are available | Present recommendation with rationale, user must explicitly confirm | | **Must-ask** | Required information is missing; multiple options with irreversible impact; project-specific preference required | Ask structured question, wait for answer | ### Question Format — How to Ask Use one of four question types, each with a text label: **[Collect] Information gathering** — used when required input is missing: ``` [Collect] [topic] needs [specific information] Background: [why this information is needed] Please provide: [what exactly is needed] ``` **[Confirm] Recommendation** — used when presenting a default for confirmation: ``` [Confirm] [decision point] Recommendation: [option] Rationale: [why this option is recommended] Alternative: [other option(s)] Please confirm whether to adopt the recommendation, or choose an alternative. ``` **[Conflict] Conflict resolution** — used when checks conflict or overlap: ``` [Conflict] [Check ID] [issue description] Finding: [specific conflict content] Suggested resolution: [keep/merge/remove] — [reason] Please confirm: adopt suggestion / other approach ``` **[Done] Phase confirmation** — used at every phase transition: ``` [Done] Phase N: [phase name] Deliverables written to dvp_workspace/: - [file1.md] — [one-line description] - [file2.md] — [one-line description] Output summary: - [key output 1] - [key output 2] - Assumptions made: [if any] Next: Phase N+1: [phase name] Will proceed after your confirmation. Let me know if adjustments are needed. ``` ### Batching Rules - Combine multiple questions from the same phase into **one batch** rather than asking one by one. - Order by priority: Must-ask first, Recommend-confirmation second. - No more than 5 questions per batch. - Recommendation-type questions must include rationale; user must explicitly confirm. ### Per-Phase Question Guide | Phase | Must-ask | Recommend | Self-decide | |-------|----------|-----------|-------------| | 1. Collection | Protocol/CRF availability, template availability, material format | Default 4-sheet format (if no template) | Study design extraction, visit structure, data modules from materials | | 2. Scope & Strategy | Scope boundaries, Edit Check coverage, key data confirmation | Validation method assignment, risk prioritization | Standard module strategy selection | | 3. Design Checks | Ambiguous thresholds/boundaries, query language preference (CN/EN) | Check coverage density, severity grading | Check ID naming, standard check logic | | 4. Alignment | Conflict resolution, feasibility trade-offs | Query burden assessment, low-priority rule consolidation | Numbering corrections, wording refinements | | 5. Draft | Unresolvable template column mapping | Document section detail level | JSON construction, format details | | 6. Review | Must-fix item changes | Should-fix item adoption | Nice-to-have items (default: no change) | ## Key Principles 1. **Interactive pacing**: MUST present a [Done] summary at every phase transition and MUST wait for explicit user confirmation before loading the next phase file. MUST NOT proceed past a phase boundary without user approval. 2. **Domain accuracy**: MUST use standard clinical DM domain abbreviations (AE, LB, VS, DM, IE, CM, EX, PE, SC, MH, DS). MUST use standard check-type labels (Completeness, Consistency, Range, Cross-Module, Timeline). MUST NOT invent non-standard terminology. 3. **Practical focus**: Every check rule MUST include a Logic Rule that evaluates to a boolean (true/false) outcome. MUST NOT produce checks without a testable condition. 4. **Risk-based**: Checks for modules rated High risk in `risk-assessment.md` MUST have at least 5 checks per module. Safety-critical modules (AE/SAE, Exposure/IP) MUST have at least one Critical-severity check. 5. **No hallucination**: MUST NOT generate check rules for protocol details not present in the user-provided materials. If a check requires a protocol value that is missing, MUST ask the user via [Collect] before creating the check. 6. **Language adaptation**: MUST write all query wording, [Done] summaries, and user-facing messages in the same language the user is using in conversation. If the user writes in Chinese, output MUST be in Chinese. If in English, output MUST be in English.

path: agents/dvp-reviewer.md
content: ---
name: dvp-reviewer
description: >
  DVP quality reviewer agent. Use when the user asks to "review DVP", "check DVP quality",
  "internal review DVP", or after a DVP draft is generated and the
  user wants a quality check. Performs comprehensive review covering completeness,
  logical consistency, expression quality, and numbering standards.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash
---

# DVP Reviewer

You are a clinical Data Management quality reviewer specializing in Data Validation Plans.

## Review Scope

When asked to review a DVP, systematically check these five dimensions. For each dimension, perform the verification method and apply the fail conditions defined below.

### 1. Completeness

Verification: Cross-reference the check list against the declared scope document.
- All modules declared in scope have at least one check. **Fail: Module with no checks → Must Fix.**
- All key variables have associated checks. **Fail: Key variable with no check → Must Fix.**
- All High-risk areas have at least 3 checks. **Fail: High-risk area with fewer than 3 checks → Should Fix.**
- At least one cross-module check exists per related domain pair. **Fail: No cross-module check → Should Fix.**
- External data sources have reconciliation checks. **Fail: Source with no reconciliation → Should Fix.**

### 2. Logical Consistency

Verification: Compare every pair of checks within each module.
- No duplicate logic under different Check IDs. **Fail: Duplicate logic → Must Fix (merge or remove).**
- No contradictory checks (one requires X, another requires not-X for the same condition). **Fail: Contradiction → Must Fix.**
- No overlap with known edit checks unless marked as intentional. **Fail: Unintentional overlap → Should Fix.**
- Date/time logic uses consistent reference dates across modules. **Fail: Inconsistent baseline → Should Fix.**
- Severity grading is consistent for similar issues. **Fail: Inconsistent severity without rationale → Should Fix.**

### 3. Expression Quality

Verification: Read each check's description, logic, and query wording.
- Descriptions follow `{Category}: {specific finding}` pattern. **Fail: Vague description → Should Fix.**
- Logic rules are boolean expressions, not narrative text. **Fail: Non-testable logic → Must Fix.**
- Query wording follows `[Specific finding]. Please [expected action].` template. **Fail: Generic query → Should Fix.**
- No undefined abbreviations. **Fail: Undefined abbreviation → Nice to Have.**

### 4. Numbering Standards

Verification: Extract all Check IDs and group by module prefix.
- Check IDs match `{MODULE}-{NNN}` format. **Fail: Non-standard format → Must Fix.**
- Sequential numbering with no gaps. **Fail: Gap in numbering → Must Fix.**
- No duplicate IDs. **Fail: Duplicate ID → Must Fix.**
- Consistent module prefixes. **Fail: Mixed prefixes → Must Fix.**

### 5. Risk Coverage

Verification: Map checks to risk areas and verify density.
- Safety-critical data has at least one Critical-severity check. **Fail: Safety module with no Critical check → Must Fix.**
- Primary endpoint data has at least 2 checks. **Fail: Fewer than 2 checks → Must Fix.**
- SAE/Death reporting timeline checks exist. **Fail: No timeline check → Must Fix.**
- Inclusion/exclusion violation detection exists. **Fail: No I/E check → Should Fix.**

## Output Format

Produce a structured review report:

```
DVP Review Report

Scope: [modules reviewed]
Date: [date]

Findings Summary:
- Must Fix: N items
- Should Fix: N items
- Nice to Have: N items

Detailed Findings:
[For each finding]
- Finding ID: [F-NNN]
- Category: [Completeness/Consistency/Expression/Numbering/Risk]
- Severity: [Must Fix / Should Fix / Nice to Have]
- Affected Check IDs: [affected check IDs]
- Description: [what was found]
- Recommendation: [recommended fix]

Overall Assessment: [Pass / Pass with Changes / Major Revision Needed]
```

## Clinical Domain Review Rules

When reviewing checks for each module, verify these domain-specific requirements:

- **AE/SAE**: MUST verify checks cover MedDRA coding consistency, CTCAE grading completeness, causality assessment fields, SAE timeline reporting. If any of these areas has no check, flag as Must Fix.
- **Lab**: MUST verify checks cover normal range flagging, unit consistency across visits, trending detection for repeat measures. If lab external data reconciliation is missing, flag as Should Fix.
- **Visit**: MUST verify checks cover visit window compliance, missed visit detection, out-of-sequence visits. If visit window checks are missing, flag as Must Fix.
- **ConMed**: MUST verify checks cover indication-AE linkage, date overlap with AE periods, route/dose logic. If ConMed-AE cross-module checks are missing, flag as Should Fix.
- **Exposure/IP**: MUST verify checks cover dosing compliance, treatment duration, dose modifications. If dose limit checks are missing for a study with dose modifications, flag as Must Fix.
- **Inclusion/Exclusion**: MUST verify checks confirm criteria compliance. If no I/E violation detection check exists, flag as Must Fix.
- **Demography**: MUST verify checks cover age calculation logic, informed consent date before any study procedure. If age calculation check is missing, flag as Should Fix.
- **Efficacy**: MUST verify endpoint checks match SAP definitions. If SAP is available and endpoint checks are missing, flag as Must Fix.

## Review Process

1. Read the DVP content from `dvp_workspace/dvp_content.json`. Also read `dvp_workspace/checks-final.md`, `dvp_workspace/scope.md`, `dvp_workspace/key-data.md`, and `dvp_workspace/risk-assessment.md` for cross-referencing.
2. Check each of the 5 dimensions systematically. For each dimension, apply the verification method and fail conditions defined in the Review Scope section above.
3. For each finding, record: Finding ID (F-NNN), Category, Severity (Must Fix / Should Fix / Nice to Have), Affected Check IDs, Description, and Recommendation.
4. Compile all findings into the structured report format defined in the Output Format section.
5. Write the report to `dvp_workspace/review-report.md`.
6. Provide an overall assessment (Pass / Pass with Changes / Major Revision Needed).


path: references/example-output.md
content: # Example DVP Output

## Example Study Context

- Protocol: XYZ-2024-001
- Phase: III
- Indication: Non-Small Cell Lung Cancer (NSCLC)
- Design: Randomized, double-blind, placebo-controlled

## Example Check Rules

### AE Module

| Check ID | Category | Description | Logic | Query Wording | Severity | Method |
|----------|----------|-------------|-------|---------------|----------|--------|
| AE-001 | Completeness | AE start date missing | If AE term is filled but start date is empty | Adverse event term is reported but start date is missing. Please provide the start date. | Major | System |
| AE-002 | Consistency | AE start date before informed consent | If AE start date < informed consent date | The start date of adverse event is before the date of informed consent. Please verify. | Major | SAS |
| AE-003 | Consistency | SAE without SAE form | If AE seriousness = Yes but no corresponding SAE narrative exists | Serious adverse event is reported but the SAE narrative form is not completed. Please complete the SAE form. | Critical | System |
| AE-004 | Timeline | AE end date before start date | If AE end date is not null and AE end date < AE start date | The end date of adverse event is before the start date. Please verify both dates. | Major | System |
| AE-005 | Cross-Module | AE without corresponding visit | If AE reported but no visit record within ±3 days of AE start date | Adverse event is reported but there is no corresponding visit record. Please confirm if the visit was conducted. | Minor | SAS |

### Visit Module

| Check ID | Category | Description | Logic | Query Wording | Severity | Method |
|----------|----------|-------------|-------|---------------|----------|--------|
| VS-001 | Timeline | Visit outside window | If actual visit date outside protocol-defined window (±3 days) | Visit date is outside the protocol-defined visit window. Please provide reason for out-of-window visit. | Minor | SAS |
| VS-002 | Completeness | Missing scheduled visit | If expected visit per schedule has no corresponding visit record | Expected visit [Visit Name] has no corresponding visit record. Please confirm if the visit was conducted or missed. | Major | Listing |

### Lab Module

| Check ID | Category | Description | Logic | Query Wording | Severity | Method |
|----------|----------|-------------|-------|---------------|----------|--------|
| LB-001 | Reconciliation | Lab data mismatch with external | If internal lab record does not match external lab transfer on [test, date, value] | Laboratory data discrepancy identified between CRF and central lab data. Please verify. | Major | Reconciliation |
| LB-002 | Consistency | Lab unit inconsistent | If lab unit for same test changes between visits without documented reason | Unit for [lab test] changed from [Unit A] to [Unit B] between visits. Please verify. | Minor | SAS |

### Inclusion/Exclusion Module

| Check ID | Category | Description | Logic | Query Wording | Severity | Method |
|----------|----------|-------------|-------|---------------|----------|--------|
| IE-001 | Consistency | Subject not meeting age criterion | If subject age at screening < 18 or > 75 | Subject age at screening does not meet the protocol-defined age criterion (18-75). Please verify date of birth and informed consent date. | Critical | SAS |
| IE-002 | Completeness | I/E criteria not fully assessed | If any I/E criterion has missing response (Yes/No) | Not all inclusion/exclusion criteria have been assessed. Please complete the assessment for all criteria. | Major | System |

### Exposure/IP Module

| Check ID | Category | Description | Logic | Query Wording | Severity | Method |
|----------|----------|-------------|-------|---------------|----------|--------|
| EX-001 | Consistency | Dose exceeds protocol-defined maximum | If administered dose > protocol-specified max dose | Administered dose exceeds the protocol-defined maximum dose. Please verify the dose and provide reason. | Critical | System |
| EX-002 | Timeline | Treatment start date after AE onset | If first dose date > first AE start date for treatment-emergent AE check | Treatment start date is after the first adverse event onset date. Please verify treatment and AE dates. | Major | SAS |

## Example External Data Reconciliation

| Recon ID | Data Source | Key Fields | Method | Frequency |
|----------|------------|------------|--------|-----------|
| RECON-001 | Central Lab | Sample ID, Test Name, Collection Date, Result | Automated | Per transfer |
| RECON-002 | SAE Reporting | Subject ID, AE Term, SAE Date | Semi-automated | Per event |
| RECON-003 | Randomization | Subject ID, Randomization Date, Treatment Arm | Automated | Per randomization |


path: references/excel-spec.md
content: # Excel Output Specification

## Default Format (4 Sheets)

When no user template is provided, generate Excel with these 4 sheets.

### Sheet 1: Check List

| Column | Header | Width | Description |
|--------|--------|-------|-------------|
| A | Check ID | 12 | Unique identifier (e.g., AE-001) |
| B | Module | 10 | Domain/module name |
| C | Category | 15 | Completeness/Consistency/Range/Cross-Module/Timeline |
| D | Check Description | 35 | Clear description of the check |
| E | Logic Rule | 30 | Exact logical condition |
| F | Applicable Scope | 20 | Which subjects/visits/conditions |
| G | Trigger Condition | 20 | When the check fires |
| H | Query Wording | 35 | Exact query text for sites |
| I | Severity | 10 | Critical/Major/Minor |
| J | Execution Method | 15 | System/SAS/Listing/Manual/Reconciliation |
| K | Status | 8 | Active/Inactive |
| L | Notes | 20 | Additional notes or comments |

**Formatting**:
- Header row: bold, white text on blue (#4472C4) background, centered, wrapped
- Module grouping: alternate row colors by module (light blue #D9E2F3 / white)
- Severity coloring: Critical=red (#FF4444) bold white text, Major=orange (#FFA500), Minor=yellow (#FFFF00)
- Freeze top row (A2)
- Auto-filter enabled on all columns
- All cells: thin border, vertical top alignment, text wrap

### Sheet 2: Summary

Layout as key-value pairs:

| Label | Content |
|-------|---------|
| Document Title | Data Validation Plan - [Protocol Number] |
| Protocol Number | [from Phase 1] |
| Study Phase | [from Phase 1] |
| Indication | [from Phase 1] |
| Sponsor | [from Phase 1] |
| Version | 1.0 |
| Date | [generation date] |
| Author | [user name or DM team] |
| Scope | [modules in scope] |
| Key Data | [critical variables list] |
| Risk Summary | [key risk areas] |
| Validation Strategy | [overall approach summary] |

Followed by a Roles & Responsibilities table:

| Role | Responsibility |
|------|---------------|
| [role] | [responsibility] |

**Formatting**:
- Labels in column A: bold, width 25
- Values in column B: wrapped text, width 60
- Roles table has header row with blue background

### Sheet 3: Revision History

| Column | Header | Width |
|--------|--------|-------|
| A | Version | 10 |
| B | Date | 15 |
| C | Author | 15 |
| D | Description of Changes | 40 |
| E | Reviewer | 15 |
| F | Approval Status | 15 |

**Formatting**: Header with blue background, thin borders, text wrap.

### Sheet 4: Ext Data Recon

| Column | Header | Width | Description |
|--------|--------|-------|-------------|
| A | Recon ID | 12 | Unique identifier (e.g., RECON-001) |
| B | Data Source | 15 | Lab/ECG/Imaging/SAE/Randomization/Other |
| C | Provider | 20 | External data provider name |
| D | Key Fields | 25 | Matching fields between internal and external data |
| E | Recon Method | 15 | Automated/Semi-automated/Manual |
| F | Frequency | 15 | Per transfer/Weekly/Monthly/Per milestone |
| G | Discrepancy Handling | 30 | How discrepancies are resolved |
| H | Responsible Party | 15 | Who performs reconciliation |
| I | Notes | 20 | Additional notes |

## Template Mode

When a user-provided template is used:
1. Read the template's existing sheet names and column headers
2. Map DVP content to the template's structure using flexible field name matching
3. Preserve the template's formatting and styles
4. Add data to existing sheets; do not create new sheets unless necessary
5. Respect any validation rules or dropdowns in the template

### Field Name Mapping

When mapping to template columns, recognize these common variations:

| Standard Field | Common Aliases |
|---------------|----------------|
| check_id | Check ID, CheckID, Check Number |
| module | Module, Domain |
| category | Category, Type, Check Category |
| description | Description, Check Description, CheckDesc |
| logic | Logic, Logic Rule, Rule |
| scope | Scope, Applicable Scope |
| trigger | Trigger, Trigger Condition |
| query_wording | Query, Query Wording, Query Text |
| severity | Severity, Priority |
| method | Method, Execution Method |
| status | Status |
| notes | Notes, Comments |


path: references/section-catalog.md
content: # DVP Document Structure Catalog

Standard sections in a Data Validation Plan document.

## Required Sections

### 1. Purpose

State the purpose of the DVP: to define the data validation approach, checks, and procedures for the clinical study.

### 2. Scope

Define what the DVP covers:
- Study identifier and protocol number
- Data modules/domains in scope
- Types of validation covered (edit checks, manual review, SAS programs, listings)
- What is explicitly out of scope

### 3. Roles & Responsibilities

Define who is responsible for each aspect of data validation:

| Role | Responsibility |
|------|---------------|
| Lead DM | Overall DVP ownership, strategy approval |
| DM | Execute validation checks, raise queries |
| DB Programmer | Implement edit checks, SAS programs |
| Biostatistician | Confirm analysis-driven validation needs |
| Medical Monitor | Review clinical logic of checks |
| Project Manager | Milestone alignment |

### 4. Data Review Strategy

Overall approach to data review:
- Frequency of data review
- Review milestones aligned with study timeline
- Prioritization of review activities
- Escalation procedures for critical findings

### 5. Validation Check Details

The core of the DVP — all check rules organized by module. Each check includes:
- Check ID, description, logic, trigger, query wording, priority, method
- Organized by domain/module with clear section headers

### 6. External Data Reconciliation

Plan for reconciling external data sources:
- Lab data
- ECG data
- Imaging data
- SAE reporting (MedWatch/CIMOS)
- Randomization data
- Other third-party data

For each: reconciliation method, frequency, key matching fields, discrepancy handling.

### 7. Query Management Rules

How queries are managed:
- Query generation rules (automatic vs manual)
- Query aging and escalation
- Query resolution expectations
- Query categorization (critical, major, minor)

### 8. Review Frequency & Milestones

Timeline for data review activities:
- Routine review frequency (e.g., weekly, biweekly)
- Milestone-driven reviews (database lock, interim analysis)
- SAE/safety data review frequency
- Special review triggers

### 9. Revision History

Track document changes:

| Version | Date | Author | Description |
|---------|------|--------|-------------|
| 1.0 | YYYY-MM-DD | Name | Initial draft |

### 10. Appendix

Supporting materials:
- Complete check list (cross-reference to Excel)
- Reference documents list
- Domain-to-module mapping
- Abbreviations and definitions


path: references/stages/phase-1-collection.md
content: # Phase 1: Collection

## Goal

Gather all input materials needed to compose the DVP. Understand the study context, key data, and validation requirements.

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content |
|------|---------|
| `study-overview.md` | Protocol number, phase, indication, sponsor, study design, primary/secondary endpoints |
| `materials-received.md` | Materials received, format, coverage, and missing items |
| `visit-schedule.md` | Visit numbers, names, windows (in days), assessments per visit (as a table) |
| `data-modules.md` | Identified domains/modules, key fields per module (as a table) |
| `assumptions-and-gaps.md` | Assumptions made + unresolved gaps (as a table with Status column: Open/Resolved) |

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Collect]** and **[Done]** question types.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Whether user has Protocol/CRF | Must-ask | Required materials — cannot proceed without |
| Material format (paste/file/Q&A) | Must-ask | Determines how to ingest information |
| Whether user has a DVP template | Must-ask | Determines output format |
| Default 4-sheet format (no template) | Recommend | Present default, user confirms |
| Study design extraction from materials | Self-decide | Derive from provided materials |
| Visit structure, data modules | Self-decide | Derive from provided materials |
| Missing details not in materials | Must-ask | Ask targeted questions for gaps |

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 1 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Request Input Materials | Ask user for Protocol, CRF, and other materials |
| 2 | Confirm DVP Template | Determine output format (user template or default) |
| 3 | Analyze Input Materials | Extract study design, key data, visit structure, data modules |
| 4 | Identify Gaps | Ask targeted questions for missing information |
| 5 | Present Summary | Output Phase 1 summary and confirm completion |

#### Decomposition

- **Sub-task 3: Analyze Input Materials** — Decompose by material type when 3+ materials are provided (e.g., `Analyze Input Materials: Protocol`, `Analyze Input Materials: CRF`).

## Steps

### Step 1: Request Input Materials

**[Collect]** Ask the user to provide the following materials (any format: paste text, file path, or verbal description):

| Material | Priority | Purpose |
|----------|----------|---------|
| Protocol | Required | Understand study design, endpoints, visit schedule |
| CRF/eCRF | Required | Identify data fields and collection structure |
| SAP | Optional | Understand analysis needs that drive validation |
| Edit Check Spec | Optional | Identify system-level checks already in place |
| Database Build Docs | Optional | Understand DB structure and constraints |
| Lab/External Data Specs | Optional | Plan external data reconciliation |
| Project Timeline | Optional | Align validation milestones |
| DVP Template | Optional | Use user's preferred output format |

Batch all collection questions into one prompt. Example:

```
[Collect] Materials needed for DVP composition
  Background: The following materials are needed to compose the DVP
  Please provide (paste text, file paths, or verbal descriptions):
  1. [Required] Protocol — study protocol document
  2. [Required] CRF/eCRF — case report form
  3. [Optional] SAP / Edit Check Spec / DB Build Docs / External data specs
  4. [Optional] DVP Excel template — output will follow your template format
  Please provide whatever materials you have available — all are not required upfront.
```

### Step 2: Confirm DVP Template

**[Confirm]** Ask specifically whether the user has a DVP Excel template. If yes, read the template to understand:
- Sheet names and structure
- Column headers in Check List
- Required fields vs optional fields
- Formatting conventions

If no template is provided:
```
[Confirm] Output format
  Recommendation: Use the default 4-sheet format (Check List / Summary / Revision History / Ext Data Recon)
  Rationale: This is the industry-standard structure when no template is provided
  Alternative: Use a custom structure you define
  Please confirm whether to adopt the recommendation.
```

### Step 3: Analyze Input Materials

**[Self-decide]** After receiving materials, analyze and summarize:
1. **Study design**: Phase, indication, sponsor, study type
2. **Key data points**: Primary/secondary endpoints, critical variables
3. **Visit structure**: Schedule of assessments, visit windows
4. **Data modules**: Which domains are in scope (AE, Lab, ConMed, etc.)
5. **Existing checks**: What's already handled by the system. If the user did not provide an Edit Check Spec, MUST record "No Edit Check Spec provided — cannot assess existing system checks" in `assumptions-and-gaps.md` and MUST NOT assume any checks are already in place.

### Step 4: Identify Gaps

**[Collect]** List any critical information missing from the provided materials. Ask targeted questions to fill gaps. Do not fabricate study details.

Batch all gap questions together. Example:
```
[Collect] Items to clarify from the protocol
  Background: The following information was not found in the provided materials but is needed for DVP composition
  Please provide:
  1. [Visit windows] What is the allowed window (in days) for each visit?
  2. [SAE reporting] What is the SAE reporting timeline (in hours)?
  3. ...
```

### Step 5: Present Summary

Before presenting the summary, write all five deliverable files listed in the Deliverables section above to `dvp_workspace/`.

**[Done]** Output a structured summary including:
- Study overview (protocol number, indication, phase, design)
- Available materials list
- Key data and modules identified
- Template decision (user template or default)
- Outstanding questions (if any)

```
[Done] Phase 1: Collection
  Deliverables written to dvp_workspace/:
  - study-overview.md — Study design and endpoints
  - materials-received.md — Materials inventory
  - visit-schedule.md — Visit schedule with assessments
  - data-modules.md — Data modules and key fields
  - assumptions-and-gaps.md — Assumptions and gaps

  Output summary:
  - Study overview: [Protocol / Phase / Indication / Design]
  - Available materials: [list]
  - Key data and modules identified: [list]
  - Template decision: [user template / default 4-sheet]
  - Assumptions made: [if any]

  Next: Phase 2: Scope & Strategy
  Will proceed after your confirmation. Let me know if adjustments are needed.
```

Wait for user confirmation before proceeding to Phase 2.

**Task update**: Mark Phase 1 task as `completed`. Mark Phase 2 task as `in_progress`.

## Rules

- MUST NOT require all materials before starting Phase 1. MUST begin with whatever the user provides and ask [Collect] questions for gaps.
- When a Protocol is provided, MUST extract study design, visit schedule, and endpoints before proceeding to Step 4.
- For CRF analysis, MUST extract the data collection structure (forms, fields, modules). MUST NOT attempt to document every individual CRF field.
- MUST record every assumption in `assumptions-and-gaps.md` with Status = Open. MUST present all assumptions at the [Done] step for user confirmation.


path: references/stages/phase-2-strategy.md
content: # Phase 2: Scope & Strategy

## Goal

Define the validation scope, identify key data and risk points, and establish the overall validation strategy.

## Read Previous Phase

Before starting Phase 2 work, read these files from `dvp_workspace/`:

- `study-overview.md` — Study context and endpoints
- `materials-received.md` — Materials inventory
- `visit-schedule.md` — Visit structure
- `data-modules.md` — Data modules and key fields
- `assumptions-and-gaps.md` — Assumptions and gaps

These contain all Phase 1 outputs. Use them as the factual basis for scope and strategy decisions.

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content | Required Format |
|------|---------|-----------------|
| `scope.md` | Per-module classification with exclusion reasons | Table with columns: Module, Classification, Reason. Classification allowed values: `DVP Check` / `Edit Check Covered` / `Excluded`. Every module in `data-modules.md` MUST appear in this table. |
| `key-data.md` | Critical data list | Table with columns: Category, Variable, Source (Protocol/CRF/SAP), Priority. Category allowed values: `Primary Endpoint` / `Secondary Endpoint` / `Safety-Critical` / `Regulatory Key Field` / `Operational`. |
| `risk-assessment.md` | Risk areas with ratings | Table with columns: Area, Risk Level, Rationale, Affected Modules. Risk Level allowed values: `High` / `Medium` / `Low`. Every High-rated area MUST map to at least one module. |
| `validation-methods.md` | Per-module method matrix | Table with columns: Module, Method, Rationale. Method allowed values: `System Edit Check` / `SAS Program` / `Listing Review` / `Direct Query` / `Reconciliation`. Every module classified as `DVP Check` in `scope.md` MUST appear in this table. |
| `module-strategy.md` | Per-module strategy | Table with columns: Module, Check Types, Key Fields, Method, Notes. Check Types MUST use the standard labels: `Completeness` / `Consistency` / `Range` / `Cross-Module` / `Timeline` / `Reconciliation`. |

If new assumptions or gaps are identified during this phase, append them to `assumptions-and-gaps.md`.

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Confirm]** and **[Done]** question types.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Scope boundaries (in/out modules) | Must-ask | Defines entire DVP coverage |
| Edit Check coverage overlap | Must-ask | Avoids duplication |
| Key data confirmation | Must-ask | User verifies critical data list |
| Validation method per category | Recommend | Default based on industry practice |
| Risk prioritization | Recommend | Default based on data criticality |
| Standard module strategy | Self-decide | Apply standard templates |

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 2 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Define Data Cleaning Scope | Classify modules as DVP check, Edit Check covered, or excluded |
| 2 | Identify Key Data and Variables | List critical data and key variables from Phase 1 |
| 3 | Assess Risk Points | Identify risk areas based on study complexity |
| 4 | Define Validation Methods | Assign validation method per data category |
| 5 | Define Module-Level Strategy | Outline per-module validation approach |
| 6 | Present Strategy | Output Phase 2 strategy summary and confirm completion |

#### Decomposition

- **Sub-task 1: Define Data Cleaning Scope** — Decompose by data module when classifying scope (e.g., `Define Data Cleaning Scope: AE/SAE`).
- **Sub-task 5: Define Module-Level Strategy** — Decompose by in-scope module (e.g., `Define Module-Level Strategy: AE/SAE`).

## Steps

### Step 1: Define Data Cleaning Scope

**[Self-decide]** Based on Phase 1 outputs, determine:
- Which data modules are in scope for validation
- Which modules are covered by system edit checks (no additional DVP checks needed)
- Which modules require manual/offline validation

**[Must-ask]** Present the scope boundary for user confirmation:
```
[Collect] Validation scope confirmation
  Background: Based on material analysis, here is the proposed validation scope
  Please confirm the scope classification for each module:
  1. [Module name] — DVP check / Covered by Edit Check / Excluded
  2. ...
```

### Step 2: Identify Key Data and Variables

**[Self-decide]** List critical data and key variables from Phase 1 materials:
- Primary and secondary endpoints
- Safety-critical data (SAE, death, discontinuation)
- Regulatory submission key fields
- Variables that directly impact analysis

**[Must-ask]** Confirm the key data list with the user:
```
[Collect] Key data confirmation
  Background: The following key data was identified from the protocol
  Please confirm whether anything is missing or needs adjustment:
  - Primary endpoints: [...]
  - Safety-critical data: [...]
  - Other key data: [...]
```

### Step 3: Assess Risk Points

**[Self-decide]** Identify risk areas based on materials:
- Complex visit schedules with windows
- Third-party data (lab, ECG, imaging) requiring reconciliation
- SAE reporting timelines
- Dosing/IP accountability
- Inclusion/exclusion criteria complexity
- Open-text fields requiring manual review

### Step 4: Define Validation Methods

**[Recommend]** For each category of data, determine the appropriate validation method:

| Method | When to Use |
|--------|------------|
| System Edit Check | Real-time validation at data entry; already in EDC |
| SAS Program | Batch validation on scheduled intervals |
| Listing Review | Manual review of data listings |
| Direct Query | Point-in-time query for specific data issues |
| Reconciliation | Compare internal vs external data sources |

Present as a recommendation:
```
[Confirm] Validation method assignment
  Recommendation: [specific method assignment per module]
  Rationale: Based on data characteristics per module and industry practice
  Alternative: [if different approaches exist]
  Please confirm whether to adopt the recommendation.
```

### Step 5: Define Module-Level Strategy

**[Self-decide]** For each key module in scope, MUST write a strategy entry in `module-strategy.md` specifying: (1) the check types to apply, (2) the key fields to validate, and (3) the validation method. Use these required check-type assignments per module:

- **AE/SAE**: MUST include Completeness (required fields), Consistency (date logic), Timeline (SAE reporting window), Cross-Module (AE-to-visit linkage). Key fields: AE term, start/end dates, severity, seriousness, causality.
- **ConMed**: MUST include Cross-Module (overlap with AE dates), Consistency (indication vs AE term match). Key fields: medication name, start/end dates, indication, route, dose.
- **Exposure/IP**: MUST include Consistency (dose vs protocol), Timeline (treatment duration). Key fields: dose amount, start/end dates, treatment compliance.
- **Visit**: MUST include Timeline (visit windows), Completeness (expected visits present). Key fields: visit date, visit name, visit status.
- **Lab**: MUST include Range (normal range flags), Reconciliation (external data match), Consistency (unit consistency). Key fields: test name, result, unit, collection date.
- **Inclusion/Exclusion**: MUST include Consistency (criteria vs enrollment data). Key fields: each I/E criterion response, screening date.
- **Demography**: MUST include Consistency (age calculation), Completeness (required fields). Key fields: DOB, sex, informed consent date.
- **Efficacy**: MUST include Consistency (endpoint assessment vs SAP definition). Key fields: per SAP endpoint variables.

### Step 6: Present Strategy

Before presenting the summary, write all five deliverable files listed in the Deliverables section above to `dvp_workspace/`. Also update `assumptions-and-gaps.md` if new items were identified.

**[Done]** Output the validation strategy as a structured document including:
- Scope definition (in-scope vs out-of-scope modules)
- Key data list
- Risk assessment summary
- Validation method matrix
- Module-level strategy summaries

```
[Done] Phase 2: Scope & Strategy
  Deliverables written to dvp_workspace/:
  - scope.md — Module scope classification
  - key-data.md — Critical data list
  - risk-assessment.md — Risk areas with ratings
  - validation-methods.md — Method matrix
  - module-strategy.md — Per-module strategy
  - assumptions-and-gaps.md — [Updated / No changes]

  Output summary:
  - Validation scope: [in-scope / out-of-scope module list]
  - Key data: [list]
  - Risk assessment: [high-risk areas]
  - Validation method matrix: [method per module]
  - Module strategy: [per-module summary]

  Next: Phase 3: Design Checks
  Will proceed after your confirmation. Let me know if adjustments are needed.
```

Wait for user confirmation before proceeding to Phase 3.

**Task update**: Mark Phase 2 task as `completed`. Mark Phase 3 task as `in_progress`.

## Rules

- Modules rated `High` risk in `risk-assessment.md` MUST have more checks than modules rated `Low` risk. The check count ratio MUST be at least 2:1 between High and Low risk modules.
- MUST NOT design checks that would trigger for more than 30% of records under normal conditions unless explicitly approved by the user. If a check is expected to trigger frequently, MUST flag it at the [Done] step as a potential query-burden concern.
- If SAP is available, MUST verify that every primary endpoint variable in the SAP has at least one corresponding check in the DVP.
- MUST document every module excluded from the DVP scope in `scope.md` with a Reason column entry. MUST NOT silently omit modules.


path: references/stages/phase-3-design.md
content: # Phase 3: Design Check Content

## Goal

Design specific, executable validation check rules for each data module. Every check must be clear, testable, and actionable.

## Read Previous Phase

Before starting Phase 3 work, read these files from `dvp_workspace/`:

- `study-overview.md` (Phase 1) — Study context
- `visit-schedule.md` (Phase 1) — Visit structure
- `data-modules.md` (Phase 1) — Data modules and key fields
- `scope.md` (Phase 2) — Which modules are in scope
- `key-data.md` (Phase 2) — Critical data to cover
- `risk-assessment.md` (Phase 2) — Risk priorities
- `validation-methods.md` (Phase 2) — Validation method per module
- `module-strategy.md` (Phase 2) — Per-module strategy
- `assumptions-and-gaps.md` (Phase 1/2) — Known assumptions and gaps

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content |
|------|---------|
| `checks.md` | Complete check rules list organized by module. Each check has all 10 fields in a table. |
| `check-rationale.md` | Design decisions: why checks were designed this way, boundary conditions, items not confirmed from materials |
| `unresolved.md` | Issues still unresolved, items needing Phase 4 confirmation or user input |

If new assumptions or gaps are identified, append them to `assumptions-and-gaps.md`.

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Collect]**, **[Confirm]**, and **[Done]** question types.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Ambiguous thresholds/boundaries from protocol | Must-ask | Cannot guess protocol-specific values |
| Query language preference (CN/EN) | Must-ask | Project-specific preference |
| Check coverage density (standard/concise) | Recommend | Default to standard coverage |
| Severity grading for each check | Recommend | Default based on risk assessment |
| Check ID naming | Self-decide | Follow naming convention |
| Standard check logic design | Self-decide | Follow industry practice |

## Check Rule Structure

Each check rule MUST define all 10 fields. Every field is required — no field may be left empty:

| Field | Description | Allowed Values / Format |
|-------|-------------|------------------------|
| Check ID | Unique identifier | Format: `{MODULE_PREFIX}-{NNN}` where prefix is one of: AE, LB, VS, DM, IE, CM, EX, PE, SC, MH, DS. Numbering is zero-padded 3-digit sequential (e.g., AE-001, AE-002). |
| Module | Domain/module | MUST match a module name from `data-modules.md`. |
| Category | Check category | One of: `Completeness` / `Consistency` / `Range` / `Cross-Module` / `Timeline`. |
| Description | Clear description of what is being checked | One sentence, prefixed with the check type (e.g., "Completeness: AE start date is missing"). |
| Logic Rule | Exact logical condition | MUST be a boolean expression using field names and operators (e.g., `IF AE.aestdat IS NULL AND AE.aeterm IS NOT NULL`). |
| Applicable Scope | Which subjects, visits, or conditions apply | MUST specify population (e.g., "All subjects with at least one AE record"). |
| Trigger Condition | When this check fires | One of: `Data Entry` / `Batch (SAS)` / `Scheduled` / `Listing Review` / `Reconciliation`. |
| Query Wording | Exact query text shown to site | MUST be a complete, actionable sentence. MUST NOT be a generic phrase like "Please check" or "Please verify." |
| Severity/Priority | Severity level | One of: `Critical` / `Major` / `Minor`. Critical = patient safety or regulatory impact. Major = data integrity impact. Minor = formatting or minor inconsistency. |
| Execution Method | How the check is executed | One of: `System` / `SAS` / `Listing` / `Manual` / `Reconciliation`. |

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 3 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Clarify Design Parameters | Resolve ambiguous protocol details and confirm query language |
| 2 | Design by Module | Design checks per module covering all check types |
| 3 | Module Coverage | Ensure all applicable modules are covered |
| 4 | Assign Check IDs | Assign unique IDs following naming convention |
| 5 | Write Query Wording | Write clear, actionable query text for each check |
| 6 | Present Check Rules | Output complete check list organized by module |

#### Decomposition

- **Sub-task 2: Design by Module** — Decompose by data module (e.g., `Design by Module: AE/SAE`, `Design by Module: Lab`).
- **Sub-task 5: Write Query Wording** — Decompose by module when total check count exceeds 20 (e.g., `Write Query Wording: AE/SAE`).

## Steps

### Step 1: Clarify Design Parameters

**[Collect]** Before designing checks, batch any questions about ambiguous protocol details:

```
[Collect] Check design parameters
  Background: The following information affects check rule logic but is not clearly specified in the protocol
  Please provide:
  1. [Visit windows] Allowed window in days for each visit (e.g., ±3 days)
  2. [Age calculation] Reference date for age calculation (informed consent date or other)
  3. [SAE timeline] SAE reporting time window
  ...
```

**[Must-ask]** Confirm query language:
```
[Collect] Query language preference
  Background: Query wording in check rules requires a language selection
  Please choose: Chinese / English / Bilingual (Chinese + English)
```

**[Confirm]** Confirm coverage density:
```
[Confirm] Check coverage density
  Recommendation: Standard coverage (5-8 checks per module, covering major risk points)
  Rationale: Balances check completeness with query burden
  Alternative: Concise coverage (3-4 core checks per module)
  Please confirm whether to adopt the recommendation.
```

### Step 2: Design by Module

**[Self-decide]** Work through each module systematically. For each module, read the relevant Phase 1 & 2 outputs and design checks covering:

1. **Completeness checks**: Required fields not empty
2. **Consistency checks**: Logical consistency between related fields
3. **Range checks**: Values within expected ranges
4. **Cross-module checks**: Consistency across domains (e.g., AE dates vs visit dates)
5. **Timeline checks**: Date/time sequence and windows

### Step 3: Module Coverage

**[Self-decide]** Cover these modules as applicable to the study:

- **DM/Subject Status**: Enrollment, withdrawal, status changes
- **Demography**: DOB, sex, age calculation, ethnicity
- **Inclusion/Exclusion**: Criteria compliance, violation tracking
- **Visit**: Schedule compliance, visit windows, missed visits
- **AE/SAE**: Completeness, date logic, severity grading, SAE criteria, causality
- **ConMed**: Indication match with AE, date overlap with AE, route/dose logic
- **Exposure/IP**: Dosing compliance, treatment duration, dose modifications
- **Lab**: Collection timing, normal range flags, trending, unit consistency
- **Efficacy**: Endpoint-specific per SAP, assessment timing
- **Medical History**: Consistency with I/E criteria, ongoing conditions
- **Death/Disposition**: Date logic, reason consistency

### Step 4: Assign Check IDs

**[Self-decide]** Follow naming convention:
- Prefix with module abbreviation (AE, LB, VS, DM, IE, CM, EX, PE, SC, MH, DS)
- Sequential numbering within module (AE-001, AE-002, ...)
- Maintain a registry to avoid duplicates

### Step 5: Write Query Wording

**[Self-decide]** For each check, write the query text that would appear in the EDC system. Every query MUST follow this template:

`[Specific finding]. Please [expected corrective action].`

Examples:
- Correct: "Start date of AE is before the date of first study drug administration (AE start: {date}, first dose: {date}). Please verify and correct if necessary."
- Correct: "Adverse event term is reported but start date is missing. Please provide the AE start date."
- Incorrect (too vague): "Please check date."
- Incorrect (no action): "Date discrepancy."

MUST NOT use generic phrasing such as "Please check," "Please verify," or "Data discrepancy" without specifying what was found. MUST use the language preference confirmed in Step 1.

### Step 6: Present Check Rules

Before presenting the summary, write all three deliverable files listed in the Deliverables section above to `dvp_workspace/`. Also update `assumptions-and-gaps.md` if new items were identified.

**[Done]** Output the complete check list organized by module. For each module:
- List all checks with full details
- Summarize check count and coverage
- Flag any areas where protocol details are insufficient

```
[Done] Phase 3: Design Checks
  Deliverables written to dvp_workspace/:
  - checks.md — Complete check rules list
  - check-rationale.md — Design decisions and rationale
  - unresolved.md — Items needing Phase 4 resolution
  - assumptions-and-gaps.md — [Updated / No changes]

  Output summary:
  - Total check rules: [N]
  - Per-module breakdown:
    - AE/SAE: [N]
    - Visit: [N]
    - Lab: [N]
    - ...
  - Coverage by type: Completeness [N] / Consistency [N] / Range [N] / Cross-module [N] / Timeline [N]
  - Query language: [CN/EN]
  - Assumptions made: [if any]

  Next: Phase 4: Alignment
  Will proceed after your confirmation. Let me know if adjustments are needed.
```

Wait for user confirmation before proceeding to Phase 4.

**Task update**: Mark Phase 3 task as `completed`. Mark Phase 4 task as `in_progress`.

## Tips

- Focus on actionable checks — every rule must result in a clear pass/fail outcome.
- Avoid redundant checks that overlap with existing edit checks.
- Consider the perspective of the site: queries should be easy to understand and respond to.
- For cross-module checks, ensure the logic is feasible given the data structure.


path: references/stages/phase-4-alignment.md
content: # Phase 4: Alignment

## Goal

Confirm that all designed check rules are correct, feasible, and do not conflict with existing systems or analysis plans. Resolve any issues before drafting.

## Read Previous Phase

Before starting Phase 4 work, read these files from `dvp_workspace/`:

- `checks.md` (Phase 3) — The check list to be aligned
- `check-rationale.md` (Phase 3) — Design decisions to review
- `unresolved.md` (Phase 3) — Items to resolve in this phase
- `scope.md` (Phase 2) — Scope boundaries for alignment verification
- `key-data.md` (Phase 2) — Key data for coverage verification
- `risk-assessment.md` (Phase 2) — Risk areas for coverage verification
- `materials-received.md` (Phase 1) — Available materials (for checking evidence)
- `assumptions-and-gaps.md` — Resolve what you can here

Resolve items from `unresolved.md` during this phase. For each resolved item, update `assumptions-and-gaps.md` to mark it as Resolved.

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content |
|------|---------|
| `checks-final.md` | Aligned final check list (replaces `checks.md` from Phase 3). Same 10-field structure per check. This is the authoritative check list for downstream phases. |
| `alignment-report.md` | Corrections made: which checks were deleted, merged, or modified and why; conflict resolution results |
| `edit-check-overlap.md` | Overlap analysis with existing Edit Checks and handling decision for each overlap |

Also update `assumptions-and-gaps.md` to mark resolved items and add any new items discovered during alignment.

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Conflict]**, **[Confirm]**, and **[Done]** question types.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Overlapping check resolution (keep/merge/remove) | Must-ask | Affects DVP structure |
| Feasibility issue trade-offs | Must-ask | Affects whether checks can execute |
| Contradictory checks | Must-ask | Must be resolved before drafting |
| Query burden assessment | Recommend | Suggest consolidation, user confirms |
| Low-priority rule consolidation | Recommend | Suggest removal, user confirms |
| Numbering corrections | Self-decide | Fix automatically |
| Wording refinements | Self-decide | Improve automatically |

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 4 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Protocol Alignment Review | Verify check logic aligns with protocol requirements |
| 2 | SAP/Analysis Alignment | Verify checks support analysis needs |
| 3 | Edit Check Conflict Check | Identify and resolve overlaps with existing edit checks |
| 4 | Database Feasibility | Assess whether checks can execute against the database |
| 5 | Query Burden Assessment | Evaluate and optimize query volume |
| 6 | Present Alignment Results | Output alignment report and confirm completion |

#### Decomposition

- **Sub-task 1: Protocol Alignment Review** — Decompose by module when total check count exceeds 15 (e.g., `Protocol Alignment Review: AE/SAE`).
- **Sub-task 4: Database Feasibility** — Decompose by module when total check count exceeds 15 (e.g., `Database Feasibility: Lab`).

## Steps

### Step 1: Protocol Alignment Review

**[Self-decide]** For each check rule, perform these verifications:
- Logic verification: Extract the protocol requirement text that supports the check logic. If no supporting text exists, flag for [Must-ask].
- Trigger verification: Confirm the Trigger Condition corresponds to a protocol-defined event (data entry, scheduled visit, external data receipt). If the trigger has no protocol basis, flag for [Must-ask].
- Scope verification: Confirm the Applicable Scope population is a subset of the study population defined in `study-overview.md`. If the scope references visits or conditions not in `visit-schedule.md`, flag for [Must-ask].
- Contradiction check: For each pair of checks in the same module, confirm both checks CAN simultaneously pass. If they cannot, flag as a conflict.

**[Must-ask]** If any checks cannot be verified from the protocol, flag for confirmation:
```
[Conflict] [Check ID] Protocol alignment issue
  Finding: [This check's logic depends on protocol requirement X, but the protocol text is ambiguous]
  Suggested resolution: [Interpret as Y / Remove this check]
  Please confirm: adopt suggestion / provide the correct interpretation
```

### Step 2: SAP/Analysis Alignment

**[Self-decide]** If SAP is available:
- Verify that checks support (not conflict with) analysis needs
- Confirm that endpoint-related checks match SAP definitions
- Check that derived variables are validated consistently with analysis derivation rules

### Step 3: Edit Check Conflict Check

**[Must-ask]** Compare DVP checks against known edit checks. For each conflict found:
```
[Conflict] [Check ID] Overlap with existing Edit Check
  Finding: [DVP check logic duplicates Edit Check #EC-XXX]
  Suggested resolution: Remove — [this logic is already covered by the edit check]
  Alternative: Keep as a supplementary check
  Please confirm: adopt suggestion / keep / merge
```

Batch all conflict items into one prompt.

### Step 4: Database Feasibility

**[Self-decide]** For each check, assess:
- Can the required fields be queried from the database?
- Are the referenced variables available and correctly named?
- Is the execution method feasible (SAS, listing, manual)?

**[Must-ask]** If feasibility issues are found:
```
[Conflict] [Check ID] Database feasibility issue
  Finding: [Required field Y does not exist in the database / execution method is not feasible]
  Suggested resolution: [Change execution method / Remove this check / Adjust logic]
  Please confirm: adopt suggestion / other approach
```

### Step 5: Query Burden Assessment

**[Recommend]** Evaluate:
- Are there checks that would generate excessive queries?
- Can any checks be consolidated to reduce query volume?
- Are query wordings clear enough to avoid back-and-forth with sites?

```
[Confirm] Query burden assessment
  Recommendation: Merge [Check A] and [Check B] to reduce query volume
  Rationale: Both checks share similar logic; merging preserves coverage while reducing ~[N] queries
  Alternative: Keep them separate
  Please confirm whether to adopt the recommendation.
```

### Step 6: Present Alignment Results

Before presenting the summary, write all three deliverable files listed in the Deliverables section above to `dvp_workspace/`. Also update `assumptions-and-gaps.md` to mark resolved items.

**[Done]** Output a structured alignment report:

```
[Done] Phase 4: Alignment
  Deliverables written to dvp_workspace/:
  - checks-final.md — Aligned final check list
  - alignment-report.md — Corrections and resolution log
  - edit-check-overlap.md — Edit check overlap analysis
  - assumptions-and-gaps.md — [Updated / No changes]

  Output summary:
  - Protocol alignment: [N] confirmed / [N] corrected
  - Edit Check conflicts: [N] overlaps resolved ([N] removed / [N] merged / [N] kept)
  - Feasibility issues: [N] resolved
  - Query burden: [N] optimizations applied
  - Final check rule count: [N]

  Next: Phase 5: Draft
  Will proceed after your confirmation. Let me know if adjustments are needed.
```

Wait for user confirmation before proceeding to Phase 5.

**Task update**: Mark Phase 4 task as `completed`. Mark Phase 5 task as `in_progress`.

## Rules

- If a [Must-ask] conflict cannot be resolved in one exchange, MUST continue the discussion until resolution. MUST NOT skip unresolved items.
- When flagging a protocol alignment issue, MUST cite the specific protocol section number or page in the Finding description.
- If a check is rated Minor severity AND its estimated trigger rate exceeds 30% of records, MUST recommend removal at the [Done] step with rationale.
- MUST record every alignment decision (keep/merge/remove) and its rationale in `alignment-report.md`. MUST NOT make silent changes without a corresponding entry.


path: references/stages/phase-5-draft.md
content: # Phase 5: Draft

## Goal

Compile all validated content into a structured DVP document and generate the final Excel output.

## Read Previous Phase

Before starting Phase 5 work, read these files from `dvp_workspace/`:

- `checks-final.md` (Phase 4) — **IMPORTANT: Read checks-final.md, NOT checks.md.** This is the aligned authoritative check list.
- `alignment-report.md` (Phase 4) — What changed and why (for traceability)
- `study-overview.md` (Phase 1) — Study metadata for the summary section
- `scope.md` (Phase 2) — Scope definition
- `key-data.md` (Phase 2) — Key data for the summary section
- `risk-assessment.md` (Phase 2) — Risk summary for the summary section
- `validation-methods.md` (Phase 2) — Method matrix for the document
- `module-strategy.md` (Phase 2) — Per-module strategy
- `assumptions-and-gaps.md` — Final assumptions list

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content |
|------|---------|
| `dvp_content.json` | Structured JSON with summary, checks, revisions, and reconciliation sections (schema defined in Step 3) |
| `DVP_<ProtocolNumber>_v1.0.xlsx` | Final Excel output generated by `scripts/generate_xlsx.py` |

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Confirm]** and **[Done]** question types. This phase has the fewest questions.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Template column mapping (unresolvable) | Must-ask | Cannot guess field mappings |
| Document section detail level | Recommend | Default to standard detail |
| JSON construction | Self-decide | Follow defined schema |
| Format details | Self-decide | Follow specification |

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 5 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Compile Document Sections | Assemble all DVP sections from previous phases |
| 2 | Format Check List | Organize check rules into the target sheet structure |
| 3 | Build JSON Input | Construct dvp_content.json with all compiled content |
| 4 | Generate Excel | Execute generate_xlsx.py to produce the output file |
| 5 | Review Output | Verify correctness of the generated Excel |
| 6 | Present Draft | Present draft summary to user for confirmation |

#### Decomposition

- **Sub-task 3: Build JSON Input** — Decompose by section (summary, checks, revisions, reconciliation) when check count exceeds 30 (e.g., `Build JSON Input: checks section`).

## Steps

### Step 1: Compile Document Sections

**[Self-decide]** Assemble the full DVP document using content from the deliverable files read at the start of this phase. The check list comes from `checks-final.md`. Study metadata comes from `study-overview.md`. Scope and strategy come from `scope.md`, `key-data.md`, `risk-assessment.md`, `validation-methods.md`.

1. **Purpose** — MUST write a 2-3 sentence paragraph stating: (a) the protocol number and study this DVP covers, (b) the validation scope (modules included), and (c) the intended audience (DM team, CRO, sponsor). Draw protocol number from `study-overview.md` and modules from `scope.md`.
2. **Scope** — Studies, modules, data types in scope
3. **Roles & Responsibilities** — Who does what in data validation
4. **Data Review Strategy** — Overall approach to data review (from Phase 2)
5. **Validation Check Details** — All check rules (from `checks-final.md`)
6. **External Data Reconciliation** — Third-party data reconciliation plan
7. **Query Management Rules** — How queries are generated, tracked, resolved
8. **Review Frequency & Milestones** — When reviews happen, aligned to project timeline
9. **Revision History** — Initial version entry
10. **Appendix** — Check list index, reference documents, mapping tables

**[Confirm]** If the detail level of document sections needs user input:
```
[Confirm] Document section detail level
  Recommendation: Standard detail — each section includes full description
  Rationale: Full detail is recommended for first draft; subsequent versions can be streamlined
  Alternative: Brief version — only essential content
  Please confirm whether to adopt the recommendation.
```

### Step 2: Format Check List

**[Self-decide]** Organize all check rules into the Check List structure. If using a user-provided template, map to the template's columns. Otherwise, use the default column structure from `references/excel-spec.md`.

**[Must-ask]** If template column names cannot be automatically matched:
```
[Collect] Template column mapping confirmation
  Background: The following column names in the template could not be auto-mapped to standard fields
  Please confirm the mapping:
  1. Template column "[Column A]" → Check description / Check logic / Other?
  2. Template column "[Column B]" → Severity / Priority / Other?
  ...
```

### Step 3: Build JSON Input

**[Self-decide]** Construct `dvp_content.json` by converting content from the deliverable files into the JSON structure below. Read `checks-final.md` for the check list. Read `study-overview.md` for summary metadata. Read `scope.md`, `key-data.md`, `risk-assessment.md`, `validation-methods.md` for scope and strategy fields.

**JSON field constraints (all apply to the schema below):**

`summary` object:
- Required fields: `protocol_number`, `study_phase`, `indication`, `version`, `scope`. MUST NOT be empty strings.
- Optional fields: `sponsor`, `author`, `key_data`, `risk_summary`, `validation_strategy`. If unknown, use `"N/A"`.
- `roles` array: MUST contain at least 2 entries (Lead DM + DM minimum).

`checks` array:
- Every object MUST contain all 12 keys shown below (`check_id`, `module`, `category`, `description`, `logic`, `scope`, `trigger`, `query_wording`, `severity`, `method`, `status`, `notes`). No keys may be omitted.
- `severity` MUST be one of: `Critical`, `Major`, `Minor`.
- `method` MUST be one of: `System`, `SAS`, `Listing`, `Manual`, `Reconciliation`.
- `status` MUST be `Active` for all checks in the initial draft.
- `check_id` MUST be unique across the entire array.
- Array MUST contain at least 1 check for every module classified as `DVP Check` in `scope.md`.

`revisions` array:
- MUST contain at least 1 entry for the initial draft.

`reconciliation` array:
- Required only if external data sources were identified in Phase 1. If none, use an empty array `[]`.
- Each entry MUST have: `recon_id`, `data_source`, `key_fields`, `method`.

```json
{
  "summary": {
    "protocol_number": "...",
    "study_phase": "...",
    "indication": "...",
    "sponsor": "...",
    "version": "1.0",
    "author": "...",
    "scope": "...",
    "key_data": "...",
    "risk_summary": "...",
    "validation_strategy": "...",
    "roles": [
      {"role": "Lead DM", "responsibility": "..."},
      {"role": "DM", "responsibility": "..."}
    ]
  },
  "checks": [
    {
      "check_id": "AE-001",
      "module": "AE",
      "category": "Completeness",
      "description": "...",
      "logic": "...",
      "scope": "...",
      "trigger": "...",
      "query_wording": "...",
      "severity": "Major",
      "method": "System",
      "status": "Active",
      "notes": ""
    }
  ],
  "revisions": [
    {"version": "1.0", "date": "YYYY-MM-DD", "author": "...", "description": "Initial draft"}
  ],
  "reconciliation": [
    {
      "recon_id": "RECON-001",
      "data_source": "Lab",
      "provider": "...",
      "key_fields": "...",
      "method": "...",
      "frequency": "...",
      "discrepancy_handling": "...",
      "responsible_party": "..."
    }
  ]
}
```

### Step 4: Generate Excel

**[Self-decide]** Execute the generation script:

```bash
python3 scripts/generate_xlsx.py \
  --input dvp_workspace/dvp_content.json \
  --output dvp_workspace/DVP_<ProtocolNumber>_v1.0.xlsx \
  [--template dvp_workspace/template.xlsx]
```

MUST verify the output file is created. If the command fails (non-zero exit code), MUST read the error output, correct `dvp_workspace/dvp_content.json`, and re-run. MUST NOT proceed to Step 5 until the file `dvp_workspace/DVP_<ProtocolNumber>_v1.0.xlsx` exists.

### Step 5: Review Output

**[Self-decide]** After generating the Excel:
1. Read back key sections to verify correctness
2. Check that all modules are represented
3. Verify Check IDs are sequential and no gaps
4. Confirm sheet structure matches expected format

### Step 6: Present Draft

Before presenting the summary, write all deliverable files listed in the Deliverables section above to `dvp_workspace/`.

**[Done]** Present the draft to the user:
- Summary of document structure
- Total check count per module
- File path to the generated Excel
- Any remaining caveats or assumptions

```
[Done] Phase 5: Draft
  Deliverables written to dvp_workspace/:
  - dvp_content.json — Structured DVP content
  - DVP_<ProtocolNumber>_v1.0.xlsx — Final Excel output

  Output summary:
  - Document structure: [N] sections
  - Check rules: [N] total (per module: AE [N], Visit [N], ...)
  - Output file: dvp_workspace/DVP_<ProtocolNumber>_v1.0.xlsx
  - Assumptions made: [if any]

  Next: Phase 6: Internal Review
  Will proceed after your confirmation. Let me know if adjustments are needed.
```

Wait for user confirmation before proceeding to Phase 6.

**Task update**: Mark Phase 5 task as `completed`. Mark Phase 6 task as `in_progress`.

## Tips

- Ensure the JSON input to the script is well-formed and complete before running.
- If the script fails, check for encoding issues (especially with Chinese characters in query wording).
- Generate a clean filename using protocol number and version.
- Keep a backup of the JSON input for potential regeneration.


path: references/stages/phase-6-review.md
content: # Phase 6: Internal Review

## Goal

Perform comprehensive internal review of the DVP to identify omissions, inconsistencies, and quality issues before finalization.

## Read Previous Phase

Before starting Phase 6 work, read these files from `dvp_workspace/`:

- `dvp_content.json` (Phase 5) — The DVP content to review
- `checks-final.md` (Phase 4) — The authoritative check list (for cross-referencing)
- `scope.md` (Phase 2) — Scope definition for completeness check
- `key-data.md` (Phase 2) — Key data for coverage verification
- `risk-assessment.md` (Phase 2) — Risk areas for coverage verification
- `assumptions-and-gaps.md` — Assumptions for review

## Deliverables

Before the [Done] step, write the following files to `dvp_workspace/`:

| File | Content |
|------|---------|
| `review-report.md` | Review findings organized by severity (Must Fix / Should Fix / Nice to Have), with handling results for each finding |

If corrections were made during the review:
- Update `dvp_content.json` with the corrected content
- Re-run `scripts/generate_xlsx.py` to regenerate the Excel
- Update `checks-final.md` if any checks were added, removed, or modified

## Interaction Guide

Follow the Interaction Protocol defined in `SKILL.md`. This phase primarily uses **[Conflict]**, **[Confirm]**, and **[Done]** question types.

| Decision point | Level | Notes |
|----------------|-------|-------|
| Must-fix item changes | Must-ask | Must get approval before modifying |
| Should-fix item adoption | Recommend | Suggest fix, user confirms |
| Nice-to-have improvements | Self-decide | Default: no change unless user requests |
| Numbering/ID fixes | Self-decide | Fix automatically |

## Review Dimensions

For each dimension, perform the verification method specified. If any check item fails, record it as a finding with the severity level indicated.

### 1. Completeness Check

Verification method: Cross-reference `checks-final.md` against `scope.md`, `key-data.md`, and `risk-assessment.md`.

- [ ] All modules classified as `DVP Check` in `scope.md` have at least one check in `checks-final.md`. **Fail condition: Module with no checks → Must Fix.**
- [ ] All variables listed in `key-data.md` have at least one associated check. **Fail condition: Key variable with no check → Must Fix.**
- [ ] All areas rated `High` in `risk-assessment.md` have at least 3 checks. **Fail condition: High-risk area with fewer than 3 checks → Should Fix.**
- [ ] At least one Cross-Module category check exists per pair of related modules. **Fail condition: No cross-module check between related domains → Should Fix.**
- [ ] If external data sources are listed in `scope.md`, at least one Reconciliation check exists per source. **Fail condition: External source with no reconciliation check → Should Fix.**

### 2. Logic Consistency

Verification method: Compare every pair of checks within the same module for duplicate or contradictory logic.

- [ ] No two checks have identical `logic` field values. **Fail condition: Duplicate logic found → Must Fix (merge or remove).**
- [ ] No two checks produce contradictory requirements (one requires X, another requires not-X for the same condition). **Fail condition: Contradiction found → Must Fix.**
- [ ] No DVP check duplicates logic already covered by edit checks in `edit-check-overlap.md` unless marked as intentional. **Fail condition: Unintentional overlap → Should Fix.**
- [ ] Date comparison logic uses consistent reference dates across modules. **Fail condition: Inconsistent date baseline across modules → Should Fix.**
- [ ] Checks with the same category and similar scope have consistent severity grading. **Fail condition: Similar checks with different severity and no documented rationale → Should Fix.**

### 3. Expression Quality

Verification method: Read each check's description, logic, and query wording.

- [ ] Every Description follows the pattern `{Category}: {specific finding}`. **Fail condition: Description does not state the category or is vague → Should Fix.**
- [ ] Every Logic Rule is a boolean expression using field names. **Fail condition: Logic is narrative text rather than a testable condition → Must Fix.**
- [ ] Every Query Wording follows the template `[Specific finding]. Please [expected action].` **Fail condition: Query uses generic phrase without specifics → Should Fix.**
- [ ] No undefined abbreviations in any field. **Fail condition: Undefined abbreviation → Nice to Have.**

### 4. Numbering Standards

Verification method: Extract all Check IDs, group by module prefix, and verify sequential ordering.

- [ ] Every Check ID matches the format `{MODULE_PREFIX}-{NNN}`. **Fail condition: Non-standard format → Must Fix.**
- [ ] Within each module prefix, NNN values are sequential with no gaps. **Fail condition: Gap in numbering → Must Fix.**
- [ ] No two checks share the same Check ID. **Fail condition: Duplicate ID → Must Fix.**
- [ ] All checks for the same module use the same prefix. **Fail condition: Mixed prefixes for one module → Must Fix.**

### 5. Risk Coverage

Verification method: Map checks to risk areas from `risk-assessment.md` and verify density.

- [ ] Safety-critical data (AE/SAE, Death, Discontinuation) has at least one Critical-severity check. **Fail condition: Safety module with no Critical check → Must Fix.**
- [ ] Primary endpoint data identified in `key-data.md` has at least 2 checks. **Fail condition: Primary endpoint with fewer than 2 checks → Must Fix.**
- [ ] SAE/Death reporting timeline requirements have a corresponding Timeline check. **Fail condition: No SAE timeline check → Must Fix.**
- [ ] Inclusion/exclusion violation detection has at least one Consistency check. **Fail condition: No I/E violation check → Should Fix.**

## Sub-Tasks

At the start of this phase, create the following sub-tasks. Each should `addBlockedBy` the Phase 6 task ID. Mark each `completed` when its step finishes.

| # | subject | description |
|---|---------|-------------|
| 1 | Automated Review | Run through all review dimensions systematically |
| 2 | Present Findings | Present Must Fix, Should Fix, and Nice to Have items |
| 3 | Address Issues | Apply approved changes and verify no regressions |
| 4 | Final Verification | Re-verify IDs, counts, and regenerate Excel if needed |
| 5 | Present Final DVP | Present finalized DVP with review completion summary |

#### Decomposition

- **Sub-task 1: Automated Review** — Decompose by review dimension (Completeness, Logic Consistency, Expression Quality, Numbering Standards, Risk Coverage). Always decompose this sub-task — there are always exactly 5 dimensions.
- **Sub-task 3: Address Issues** — Decompose by finding when 3+ findings exist (e.g., `Address Issues: AE-008 duplicate logic`).

## Steps

### Step 1: Automated Review

**[Self-decide]** Run through the review checklist above systematically. For each dimension:
- Flag specific issues with Check IDs
- Categorize by severity (Must Fix, Should Fix, Nice to Have)
- Provide specific recommendations

### Step 2: Present Findings

**[Conflict]** For Must Fix items, present one by one for approval:
```
[Conflict] [Check ID] [issue — e.g., Duplicate logic]
  Finding: [AE-008 and AE-012 share the same logic]
  Suggested resolution: Merge into one check — [keep AE-008, remove AE-012]
  Please confirm: adopt suggestion / other approach
```

**[Confirm]** For Should Fix items, batch into one recommendation:
```
[Confirm] Should Fix items (recommended changes)
  The following issues are recommended for fixing but do not affect core correctness:
  1. [CM-003] Query wording is too generic, recommend changing to "[specific wording]"
  2. [VS-005] Visit window definition conflicts with VS-009, recommend unifying to [...]
  ...
  Please confirm: adopt all / adopt selected (please specify) / skip for now
```

Nice to Have items are listed but not actioned by default.

### Step 3: Address Issues

**[Self-decide]** For each approved change:
1. Apply the change
2. Re-run the relevant Review Dimension checks for the affected module: verify no new duplicate IDs, no new logic contradictions, and no broken sequential numbering. If a new issue is introduced, revert the change and flag for [Must-ask].

### Step 4: Final Verification

**[Self-decide]** After all issues are resolved:
1. Re-verify Check ID sequence
2. Confirm total check count
3. If any corrections were made:
   a. Update `dvp_content.json` in `dvp_workspace/`
   b. Re-run `scripts/generate_xlsx.py` to regenerate the Excel
   c. Update `checks-final.md` if checks changed

### Step 5: Present Final DVP

Before presenting the summary, write the `review-report.md` deliverable to `dvp_workspace/`. If corrections were made, also update `dvp_content.json` and regenerate the Excel.

**[Done]** Present the finalized DVP:
- Final check count summary
- Review completion confirmation
- Updated Excel file path
- List of changes made during review

```
[Done] Phase 6: Internal Review
  Deliverables written to dvp_workspace/:
  - review-report.md — Review findings and handling results
  - dvp_content.json — [Updated / No changes]
  - DVP_<ProtocolNumber>_v1.0.xlsx — [Regenerated / No changes]

  Output summary:
  - Final check rule count: [N]
  - Review results: [N] Must Fix corrected / [N] Should Fix adopted / [N] Nice to Have unchanged
  - Output file: dvp_workspace/DVP_<ProtocolNumber>_v1.0.xlsx
  - Review complete — DVP is ready for distribution and team review
```

The DVP is now ready for distribution and team review.

**Task update**: Mark Phase 6 task as `completed`. All tasks are now done.

## Tips

- Review should be thorough but practical — not every check needs to be perfect on first draft.
- Prioritize must-fix issues (duplicates, contradictions, missing safety checks).
- Document all review findings for audit trail purposes.
- If the user wants to skip certain review items, document the decision and rationale.


path: scripts/generate_xlsx.py
content: #!/usr/bin/env python3
"""Generate DVP Excel file from JSON input."""

import argparse
import json
import sys
from datetime import date
from pathlib import Path

try:
    import openpyxl
    from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
    from openpyxl.utils import get_column_letter
except ImportError:
    print("Error: openpyxl is required. Install with: pip install openpyxl", file=sys.stderr)
    sys.exit(1)

HEADER_FILL = PatternFill(start_color="4472C4", end_color="4472C4", fill_type="solid")
HEADER_FONT = Font(name="Calibri", bold=True, color="FFFFFF", size=11)
MODULE_FILLS = {
    "default": PatternFill(start_color="D9E2F3", end_color="D9E2F3", fill_type="solid"),
    "alt": PatternFill(start_color="FFFFFF", end_color="FFFFFF", fill_type="solid"),
}
SEVERITY_FILLS = {
    "Critical": PatternFill(start_color="FF4444", end_color="FF4444", fill_type="solid"),
    "Major": PatternFill(start_color="FFA500", end_color="FFA500", fill_type="solid"),
    "Minor": PatternFill(start_color="FFFF00", end_color="FFFF00", fill_type="solid"),
}
THIN_BORDER = Border(
    left=Side(style="thin"),
    right=Side(style="thin"),
    top=Side(style="thin"),
    bottom=Side(style="thin"),
)


def _apply_header(cell):
    cell.font = HEADER_FONT
    cell.fill = HEADER_FILL
    cell.alignment = Alignment(horizontal="center", vertical="center", wrap_text=True)
    cell.border = THIN_BORDER


def _apply_cell(cell, fill=None):
    cell.alignment = Alignment(vertical="top", wrap_text=True)
    cell.border = THIN_BORDER
    if fill:
        cell.fill = fill


def create_check_list_sheet(ws, checks):
    headers = [
        "Check ID", "Module", "Category", "Check Description", "Logic Rule",
        "Applicable Scope", "Trigger Condition", "Query Wording",
        "Severity", "Execution Method", "Status", "Notes",
    ]
    for col, header in enumerate(headers, 1):
        _apply_header(ws.cell(row=1, column=col, value=header))

    current_module = None
    fill_key = "default"
    for row_idx, check in enumerate(checks, 2):
        mod = check.get("module", "")
        if mod != current_module:
            current_module = mod
            fill_key = "alt" if fill_key == "default" else "default"
        row_fill = MODULE_FILLS[fill_key]

        values = [
            check.get("check_id", ""), mod, check.get("category", ""),
            check.get("description", ""), check.get("logic", ""),
            check.get("scope", ""), check.get("trigger", ""),
            check.get("query_wording", ""), check.get("severity", ""),
            check.get("method", ""), check.get("status", "Active"),
            check.get("notes", ""),
        ]
        for col, value in enumerate(values, 1):
            cell = ws.cell(row=row_idx, column=col, value=value)
            _apply_cell(cell, row_fill)
            if col == 9 and value in SEVERITY_FILLS:
                cell.fill = SEVERITY_FILLS[value]
                if value == "Critical":
                    cell.font = Font(bold=True, color="FFFFFF")

    widths = [12, 10, 15, 35, 30, 20, 20, 35, 10, 15, 8, 20]
    for i, w in enumerate(widths, 1):
        ws.column_dimensions[get_column_letter(i)].width = w
    ws.freeze_panes = "A2"
    ws.auto_filter.ref = ws.dimensions


def create_summary_sheet(ws, summary):
    sections = [
        ("Document Title", f"Data Validation Plan - {summary.get('protocol_number', '')}"),
        ("Protocol Number", summary.get("protocol_number", "")),
        ("Study Phase", summary.get("study_phase", "")),
        ("Indication", summary.get("indication", "")),
        ("Sponsor", summary.get("sponsor", "")),
        ("Version", summary.get("version", "1.0")),
        ("Date", summary.get("date", str(date.today()))),
        ("Author", summary.get("author", "")),
        ("", ""),
        ("Scope", summary.get("scope", "")),
        ("Key Data", summary.get("key_data", "")),
        ("Risk Summary", summary.get("risk_summary", "")),
        ("Validation Strategy", summary.get("validation_strategy", "")),
    ]
    for idx, (label, value) in enumerate(sections, 1):
        if label:
            ws.cell(row=idx, column=1, value=label).font = Font(bold=True, size=11)
        ws.cell(row=idx, column=2, value=value).alignment = Alignment(wrap_text=True)

    roles_start = len(sections) + 2
    ws.cell(row=roles_start, column=1, value="Roles & Responsibilities").font = Font(bold=True, size=12)
    hr = roles_start + 1
    for col, h in enumerate(["Role", "Responsibility"], 1):
        _apply_header(ws.cell(row=hr, column=col, value=h))
    for off, role in enumerate(summary.get("roles", [])):
        r = hr + off + 1
        ws.cell(row=r, column=1, value=role.get("role", "")).border = THIN_BORDER
        ws.cell(row=r, column=2, value=role.get("responsibility", "")).border = THIN_BORDER
        ws.cell(row=r, column=2).alignment = Alignment(wrap_text=True)

    ws.column_dimensions["A"].width = 25
    ws.column_dimensions["B"].width = 60


def create_revision_history_sheet(ws, revisions):
    for col, h in enumerate(["Version", "Date", "Author", "Description of Changes", "Reviewer", "Approval Status"], 1):
        _apply_header(ws.cell(row=1, column=col, value=h))
    for row_idx, rev in enumerate(revisions, 2):
        for col, key in enumerate(["version", "date", "author", "description", "reviewer", "status"], 1):
            cell = ws.cell(row=row_idx, column=col, value=rev.get(key, ""))
            _apply_cell(cell)
    for i, w in enumerate([10, 15, 15, 40, 15, 15], 1):
        ws.column_dimensions[get_column_letter(i)].width = w


def create_ext_data_recon_sheet(ws, items):
    headers = [
        "Recon ID", "Data Source", "Provider", "Key Fields",
        "Recon Method", "Frequency", "Discrepancy Handling", "Responsible Party", "Notes",
    ]
    for col, h in enumerate(headers, 1):
        _apply_header(ws.cell(row=1, column=col, value=h))
    for row_idx, item in enumerate(items, 2):
        for col, key in enumerate(
            ["recon_id", "data_source", "provider", "key_fields",
             "method", "frequency", "discrepancy_handling", "responsible_party", "notes"], 1
        ):
            _apply_cell(ws.cell(row=row_idx, column=col, value=item.get(key, "")))
    for i, w in enumerate([12, 15, 20, 25, 15, 15, 30, 15, 20], 1):
        ws.column_dimensions[get_column_letter(i)].width = w


def generate_from_template(input_data, template_path, output_path):
    wb = openpyxl.load_workbook(template_path)
    check_sheet = None
    for name in wb.sheetnames:
        lower = name.lower()
        if any(kw in lower for kw in ["check", "list"]):
            check_sheet = wb[name]
            break
    if check_sheet is None:
        check_sheet = wb.active

    headers = [cell.value for cell in check_sheet[1]]
    field_mapping = {
        "check id": "check_id", "module": "module", "category": "category",
        "description": "description", "check description": "description",
        "logic": "logic", "logic rule": "logic", "scope": "scope",
        "applicable scope": "scope", "trigger": "trigger",
        "trigger condition": "trigger", "query": "query_wording",
        "query wording": "query_wording", "severity": "severity",
        "priority": "severity", "method": "method",
        "execution method": "method", "status": "status", "notes": "notes",
    }
    header_to_field = {}
    for idx, header in enumerate(headers):
        if header:
            header_to_field[idx] = field_mapping.get(header.lower().strip(), header.lower().strip())

    for row_idx, check in enumerate(input_data.get("checks", []), 2):
        for col_idx, field_name in header_to_field.items():
            check_sheet.cell(row=row_idx, column=col_idx + 1, value=check.get(field_name, ""))

    wb.save(output_path)
    print(f"DVP generated using template: {output_path}")


def generate_default(input_data, output_path):
    wb = openpyxl.Workbook()
    ws = wb.active
    ws.title = "Check List"
    create_check_list_sheet(ws, input_data.get("checks", []))

    ws_s = wb.create_sheet("Summary")
    create_summary_sheet(ws_s, input_data.get("summary", {}))

    ws_r = wb.create_sheet("Revision History")
    create_revision_history_sheet(ws_r, input_data.get("revisions", [
        {"version": "1.0", "date": str(date.today()), "author": "", "description": "Initial draft"}
    ]))

    ws_e = wb.create_sheet("Ext Data Recon")
    create_ext_data_recon_sheet(ws_e, input_data.get("reconciliation", []))

    wb.save(output_path)
    print(f"DVP generated: {output_path}")


def main():
    parser = argparse.ArgumentParser(description="Generate DVP Excel file")
    parser.add_argument("--input", required=True, help="Path to JSON input file")
    parser.add_argument("--output", required=True, help="Path to output Excel file")
    parser.add_argument("--template", help="Path to Excel template (optional)")
    args = parser.parse_args()

    input_path = Path(args.input)
    if not input_path.exists():
        print(f"Error: Input file not found: {input_path}", file=sys.stderr)
        sys.exit(1)

    with open(input_path, "r", encoding="utf-8") as f:
        input_data = json.load(f)

    if args.template:
        template_path = Path(args.template)
        if not template_path.exists():
            print(f"Error: Template file not found: {template_path}", file=sys.stderr)
            sys.exit(1)
        generate_from_template(input_data, str(template_path), args.output)
    else:
        generate_default(input_data, args.output)


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)