doc-research-improvements
Research-driven critique and enhancement of Amelia architecture or ideas docs. Use with GPT-5.2 when given a design/architecture doc to analyze concepts, find sources, and propose improvements plus OSS candidates.
When & Why to Use This Skill
This Claude skill provides a research-driven framework for critiquing and enhancing technical architecture and design documents. It systematically analyzes system concepts, validates them against authoritative sources, and proposes ranked improvements alongside compatible open-source software (OSS) recommendations to ensure robust, scalable, and evidence-based system design.
Use Cases
- Architecture Peer Review: Automatically analyze complex system design documents to identify structural weaknesses, find potential bottlenecks, and suggest improvements based on industry standards.
- OSS Candidate Discovery: Identify and evaluate the best-fit open-source libraries and frameworks for a project, considering license compatibility, maturity, and technical constraints.
- Technical Concept Validation: Research and verify the feasibility of specific frameworks or methodologies (e.g., RAG, LangGraph) mentioned in a proposal using official documentation and reputable sources.
- Exploratory Idea Refinement: Transform high-level 'idea' documents into actionable technical roadmaps by identifying dependencies, risks, and necessary implementation modules.
| name | doc-research-improvements |
|---|---|
| description | Research-driven critique and enhancement of Amelia architecture or ideas docs. Use with GPT-5.2 when given a design/architecture doc to analyze concepts, find sources, and propose improvements plus OSS candidates. |
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.