documentation-agent-spec

Agent Specification: Documentation Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Documentation Agent | | **ID** | research-documentation-agent | | **Purpose** | Summarize papers using LLM with RAG pattern, extract structured data, grade source quality, and create Zettelkasten-style literature notes | | **Lifecycle Stage** | Documentation (Stage 3 of Research Framework) | | **Model** | opus (for summarization quality) or sonnet (for efficiency) | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Documentation Agent transforms raw PDFs into actionable knowledge. It extracts text from PDFs, generates summaries using RAG (Retrieval-Augmented Generation) to prevent hallucinations, extracts structured data (claims, methods, findings), calculates GRADE-inspired quality scores, and creates Zettelkasten literature notes with proper attribution. The agent achieves 75% time savings compared to manual documentation (5 minutes vs. 20 minutes per paper).

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | PDF Text Extraction | Extract readable text preserving structure | NFR-RF-D-03 | | RAG Summarization | Generate summaries grounded in source text | NFR-RF-D-01 | | Hallucination Detection | Validate claims against source content | NFR-RF-D-02 | | Structured Extraction | Extract claims, methods, datasets, findings | NFR-RF-D-03 | | GRADE Scoring | Assess evidence quality (risk of bias, consistency, etc.) | NFR-RF-D-05 | | Literature Notes | Create atomic, tagged, linked notes (Zettelkasten) | NFR-RF-D-06 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Progressive Summarization | Generate multi-level summaries (1-page, 1-paragraph, 1-sentence) | | OCR Fallback | Extract text from scanned/image-based PDFs | | Bulk Processing | Document multiple papers sequentially | | Map of Content | Generate topic-based indexes across notes |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | Execute PDF tools, manage files | Execute | | Read | Access PDFs, metadata, existing notes | Read | | Write | Save summaries, extractions, notes | Write | | Glob | Find related notes for linking | Read | | Grep | Search for hallucination validation | Read |

System Tools

| Tool | Purpose | Required | |------|---------|----------| | `pdftotext` | PDF text extraction (poppler-utils) | Yes | | `tesseract` | OCR for scanned PDFs | Optional | | `PyPDF2` | Python PDF manipulation | Optional |

LLM Integration

| Model | Purpose | Settings | |-------|---------|----------| | Claude (opus/sonnet) | Summarization, extraction | Temperature: 0.3 | | Local LLM (optional) | Fallback for privacy/cost | Temperature: 0.3 |

4. Triggers

Automatic Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Acquisition Complete | Paper acquired (UC-RF-002) | Document paper | | Workflow Stage | UC-RF-008 initiates Stage 3 | Process workflow papers |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Single Paper | `aiwg research summarize REF-XXX` | Document one paper | | Bulk Processing | `aiwg research summarize --from-acquired` | Document all acquired | | Progressive Mode | `aiwg research summarize REF-XXX --progressive` | Multi-level summaries | | Create Note | `aiwg research note-create --permanent --based-on REF-XXX` | Permanent note | | Create MoC | `aiwg research moc-create "Topic Name"` | Map of Content |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | REF-XXX Identifier | String | Command argument | Valid REF-XXX exists | | LLM Model Selection | Enum | Optional flag `--llm` | Valid model name | | Progressive Levels | Integer (1-3) | Optional flag | 1=page, 2=para, 3=sentence |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | Summary | Markdown | `.aiwg/research/knowledge/summaries/{REF-XXX}-summary.md` | Permanent | | Extraction | JSON | `.aiwg/research/knowledge/extractions/{REF-XXX}-extraction.json` | Permanent | | Literature Note | Markdown | `.aiwg/research/knowledge/notes/{REF-XXX}-literature-note.md` | Permanent | | Permanent Note | Markdown | `.aiwg/research/knowledge/notes/permanent-{topic}-{timestamp}.md` | Permanent | | Map of Content | Markdown | `.aiwg/research/knowledge/maps/{topic-slug}.md` | Permanent |

Output Schema: Structured Extraction JSON

{
  "ref_id": "REF-025",
  "extraction_timestamp": "2026-01-25T16:00:00Z",
  "llm_model": "claude-opus-4",
  "claims": [
    "Token rotation reduces CSRF risk by 80% compared to static tokens",
    "OAuth 2.0 with PKCE prevents authorization code interception",
    "Refresh token rotation improves security without UX degradation"
  ],
  "methods": [
    "Controlled experiment with 10,000 users",
    "Security analysis using formal verification",
    "User study measuring UX impact (SUS score)"
  ],
  "datasets": [
    {
      "name": "OAuth Security Dataset",
      "size": "10,000 user sessions",
      "source": "Production deployment (anonymized)"
    }
  ],
  "metrics": [
    {"name": "CSRF attack success rate", "baseline": "12%", "intervention": "2.4%"},
    {"name": "SUS usability score", "baseline": "78", "intervention": "76"}
  ],
  "findings": [
    {
      "claim": "Token rotation reduces CSRF risk by 80%",
      "statistic": "p < 0.001",
      "confidence_interval": "95% CI: [75%, 85%]"
    }
  ],
  "related_work": [
    "10.1145/3133956.3133980",
    "10.1145/3243734.3243820"
  ]
}

Output Schema: Summary Frontmatter (YAML)

---
ref_id: REF-025
title: "OAuth 2.0 Security Best Practices"
authors: ["Smith, J.", "Doe, J."]
year: 2023
summarized_date: 2026-01-25
llm_model: claude-opus-4
summary_type: full  #