Doc Research and Improvement (GPT-5.2)
Use this skill to analyze a single doc (architecture or idea), research its referenced concepts, and propose improvements with external sources and implementation candidates.
Input Parameters
| Parameter | Description | Required |
|---|---|---|
doc_path | Path to the doc to analyze. | Required (unless doc_text) |
doc_text | Raw doc content if not reading from file. | Optional |
focus_areas | Comma list: architecture, data-model, orchestration, security, observability, testing, UX, scaling, cost. | Optional |
depth | quick (top 3 items) or standard (top 5-8 items). | Optional |
constraints | Explicit constraints to respect (ex: local-first, SQLite, no background jobs). | Optional |
Repository Context (Align To)
These are core assumptions from docs/site/architecture/* and docs/site/ideas/*:
- •Amelia is a local-first, agentic coding orchestrator with LangGraph, FastAPI, and SQLite.
- •Primary workflow: Architect -> Developer -> Reviewer with human approval gates.
- •Design principles: structured handoffs, verify before done, environment as truth.
- •Drivers and trackers are pluggable abstractions.
- •Ideas are exploratory; suggest improvements without assuming commitment.
Use these as guardrails when proposing changes.
Required Workflow
- •
Ingest and summarize the doc
- •Identify goals, scope, non-goals, and assumptions.
- •Note dependencies on current architecture or roadmap phases.
- •
Extract concepts, frameworks, and techniques
- •List all explicit or implied frameworks (ex: LangGraph, RAG, SOX/ICFR, BDD).
- •Classify each as architecture, process, data, evaluation, or UI.
- •
Research and validate
- •Use authoritative sources: specs, official docs, standards, reputable research.
- •Capture at least 1 source per key concept. If none, label as hypothesis.
- •Summarize evidence in 1-2 lines with citations.
- •
Propose improvements
- •Prioritize items by impact and feasibility.
- •Provide rationale tied to evidence and Amelia constraints.
- •Include tradeoffs and risks.
- •Call out where changes touch existing modules (ex:
amelia/core/,amelia/server/).
- •
Recommend OSS candidates
- •Suggest open-source libraries or frameworks needed to implement changes.
- •Include license, maturity, and integration notes.
- •Prefer Python 3.12, FastAPI, React, SQLite compatible stacks.
Output Format
Doc Snapshot
- •Goal, scope, non-goals, assumptions
Extracted Concepts | Concept | Category | Why it matters | Sources |
Evidence and Research Notes
- •Bullet list of sources with 1-line relevance
Improvements (Ranked)
- •Title
- •Rationale + evidence (cite)
- •Tradeoffs/risks
- •Implementation notes (files/modules)
OSS and Framework Candidates | Need | Options | License | Why it fits |
Open Questions
- •Any missing inputs or decisions required
Guardrails
- •Do not contradict architecture principles unless the doc explicitly proposes it.
- •If the doc is exploratory, frame improvements as experiments or phased probes.
- •Avoid proprietary SaaS recommendations unless the doc already assumes them.
- •No hallucinated citations; if unsure, say so and suggest verification.