---
phase: 05-research-enhancement
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/openai/prompts.ts
- src/openai/parser.ts
autonomous: true
---
<objective>
Improve deep research quality through enhanced prompts and better source handling.
Purpose: The current research produces good content but loses value through poor extraction. Enhanced prompts will guide AI to produce more structured output, and improved parsing will capture more data accurately.
Output: Updated prompts with structured output guidance, parser with citation field mapping, and validation for extracted data.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/openai/prompts.ts
@src/openai/parser.ts
@src/openai/client.ts
</context>
<tasks>
<task type="auto">
<name>Task 1: Enhance research prompts with structured output guidance</name>
<files>src/openai/prompts.ts</files>
<action>
Update the research prompts to improve output quality:
1. Add a structured output section to SYSTEM_PROMPT:
- Request markdown with consistent headers (## and ### levels)
- Specify citation format: "[Source Title](URL)" inline with data
- Request explicit numeric values with units (e.g., "$X.X billion" not "large market")
2. For each framework prompt in generateResearchPrompt():
- Add explicit structure hints matching what the parser expects
- Request that numbers include their source in the same line
- Add "Cite each data point with its source URL" reminder
3. Update market-sizing prompt specifically:
- Request "TAM: $X billion (Source: [Name](URL))" format
- Same for SAM and SOM
- Request CAGR as "X.X%" format
4. Update competitive-analysis prompt:
- Request each competitor in its own ## section
- Request ### Strengths and ### Weaknesses subsections consistently
Keep the detailed research guidance - just add structure requirements.
</action>
<verify>Read src/openai/prompts.ts and confirm structured output guidance is present in SYSTEM_PROMPT and framework prompts</verify>
<done>SYSTEM_PROMPT includes citation format and structure requirements. Each framework prompt includes format hints matching parser expectations.</done>
</task>
<task type="auto">
<name>Task 2: Improve citation-to-field mapping in parser</name>
<files>src/openai/parser.ts</files>
<action>
Update the parser to map citations to their relevant fields:
1. In processCitations(), update to accept sectionMapping parameter:
```typescript
function processCitations(
rawCitations: RawCitation[],
content: string,
fieldSections: Record<string, { start: number; end: number }>
): Citation[]
```
2. Create helper function to identify which field a citation belongs to:
```typescript
function mapCitationToFields(
citation: RawCitation,
fieldSections: Record<string, { start: number; end: number }>
): string[]
```
- Match citation start_index to section ranges
- Return array of field names where citation appears
3. Update parseMarketSizingResearch():
- Before processing citations, calculate section positions:
- TAM section start/end indices
- SAM section start/end indices
- SOM section start/end indices
- Growth section start/end indices
- Pass section map to processCitations()
- Result: citations will have populated relevantFields
4. Apply same pattern to parseCompetitiveAnalysisResearch():
- Map competitor sections and their subsections
- Citations get mapped to "competitors[0].strengths", etc.
5. Keep existing parsing logic for other frameworks - just add the section mapping where it adds value (market-sizing and competitive-analysis are the highest-value improvements).
</action>
<verify>Run npm test to ensure existing tests pass. Read parser.ts and confirm citation mapping logic exists.</verify>
<done>processCitations() accepts section mapping. parseMarketSizingResearch() and parseCompetitiveAnalysisResearch() map citations to fields. relevantFields populated in output.</done>
</task>
<task type="auto">
<name>Task 3: Add data validation for extracted values</name>
<files>src/openai/parser.ts</files>
<action>
Add validation layer to catch parsing errors and adjust confidence:
1. Create validation helpers:
```typescript
function isReasonableMarketSize(value: number): boolean {
// $1M to $100T is reasonable market size
return value >= 1_000_000 && value <= 100_000_000_000_000;
}
function isReasonableGrowthRate(rate: number): boolean {
// -50% to 500% is reasonable CAGR
return rate >= -50 && rate <= 500;
}
```
2. In parseMarketSizingResearch():
- If TAM < SAM or SAM < SOM, reduce confidence by 15 (data inconsistency)
- If any market size fails isReasonableMarketSize(), reduce confidence by 10
- If growth rate fails isReasonableGrowthRate(), reduce confidence by 5
- Add validation failures to a new `warnings` array in result
3. Update ParsedResearchResult interface:
```typescript
export interface ParsedResearchResult {
data: Record<string, unknown>;
citations: Citation[];
confidence: number;
missingFields: string[];
warnings: string[]; // NEW: validation warnings
rawContent: string;
}
```
4. Add warnings to all parser functions (default to empty array for frameworks without specific validation).
5. Update parseCompetitiveAnalysisResearch():
- Warn if fewer than 3 competitors found
- Warn if any competitor has zero strengths or weaknesses
</action>
<verify>Run npm test. Read parser.ts and confirm validation helpers exist and ParsedResearchResult includes warnings.</verify>
<done>Validation helpers created. Market sizing validates TAM >= SAM >= SOM relationships. ParsedResearchResult has warnings field. Confidence adjusted for validation failures.</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] npm run build succeeds without errors
- [ ] npm test passes all tests
- [ ] SYSTEM_PROMPT includes structured output guidance
- [ ] Framework prompts include format hints
- [ ] Citation relevantFields are populated for market-sizing and competitive-analysis
- [ ] ParsedResearchResult includes warnings array
- [ ] Validation reduces confidence for inconsistent data
</verification>
<success_criteria>
- All tasks completed
- All verification checks pass
- No new TypeScript errors
- Backward compatible (existing research still works, just better)
- Prompts guide AI toward more structured output
- Citations map to specific fields
- Validation catches data inconsistencies
</success_criteria>
<output>
After completion, create `.planning/phases/05-research-enhancement/05-01-SUMMARY.md`
</output>
