| name | research-analyst |
| description | This skill should be used when the user asks to 'research codebase', 'scan tech stack', 'import documents', 'discovery questions', or needs guidance on Phase 1 research. Also trigger on 'sdd research', 'brownfield scan', 'import transcript', or 'check ecosystem'. |
Research Analyst (Phase 1)
Overview
Phase 1 systematically analyzes existing technology, codebase, and organizational context to establish the knowledge baseline for specification and design decisions.
Research Workflow
Execute structured research in this sequence:
- Brownfield/Greenfield Assessment — Determine if building new or extending existing
- Technology Stack Scan — Catalog languages, frameworks, databases, tools
- Document Import — Gather requirements docs, designs, transcripts, compliance materials
- Ecosystem Check — Map dependencies, integrations, and third-party services
- Discovery Questions — Interview stakeholders to fill knowledge gaps
- RESEARCH.md Generation — Synthesize findings into structured artifact
Brownfield vs Greenfield
Greenfield Assessment
New project with no existing codebase. Characteristics:
- Zero implementation debt
- Full technology stack choice freedom
- Complete architecture design needed
- Higher timeline risk (more unknowns)
- Compliance requirements from scratch
Actions:
- Focus research on requirements analysis
- Investigate relevant open-source alternatives
- Benchmark similar products for feature baseline
- Plan tech stack based purely on requirements fit
Brownfield Assessment
Extending existing codebase. Characteristics:
- Technology stack constraints (existing tools/languages)
- Integration points to existing systems
- Organizational technology standards to respect
- Some business logic already implemented
- Technical debt to consider
Actions:
- Scan existing codebase structure and patterns
- Document current tech stack and versions
- Map existing data models and APIs
- Identify performance bottlenecks
- Review existing test coverage
Technology Stack Scan
For brownfield projects, automatically catalog:
Languages & Runtime
- Primary language(s) with versions
- Runtime environment (Node 18.x, Python 3.11, Java 17, etc.)
- Package managers and registries
Web Frameworks
- Frontend: React, Vue, Angular, or none
- Backend: Express, FastAPI, Spring, Django
- ORM/query builders (Sequelize, SQLAlchemy, Hibernate)
Databases
- Primary: PostgreSQL, MySQL, MongoDB, etc.
- Caches: Redis, Memcached
- Search: Elasticsearch, Algolia
- Queues: RabbitMQ, Kafka, SQS
Infrastructure
- Container runtime: Docker, Podman
- Orchestration: Kubernetes, Docker Compose
- Cloud provider: AWS, GCP, Azure, on-prem
- CI/CD: GitHub Actions, GitLab CI, Jenkins
DevOps & Quality
- Testing frameworks and coverage tools
- Code quality: SonarQube, Prettier, ESLint
- Monitoring: DataDog, New Relic, Prometheus
- Logging: ELK, Splunk, CloudWatch
Security & Compliance
- Authentication: OAuth, JWT, SAML
- Data encryption standards
- Regulatory requirements: GDPR, HIPAA, SOC2
- Secrets management: Vault, AWS Secrets Manager
Generate tech stack report with version matrix and compatibility notes.
Document Import
Aggregate all existing documentation and project history:
Specification Documents
- Requirements documents (RFP, PRD, specification)
- User stories and acceptance criteria
- Functional specifications
- Non-functional requirements
Design & Architecture
- Architecture Decision Records (ADRs)
- System design documents
- Database schema documentation
- API specifications (Swagger, Postman)
Process & Compliance
- Incident postmortems
- Security assessments and audit reports
- Compliance documentation
- Standard operating procedures
Communications
- Meeting transcripts and notes
- Email threads on key decisions
- Slack/Teams channel exports
- Stakeholder feedback collection
Code & Artifacts
- README files and documentation
- Code comments explaining business logic
- Deployment guides
- Known issues and limitations list
Import strategy:
- Scan repository for documentation files
- Extract from Wiki systems (Confluence, GitHub Wiki)
- Transcribe audio/video of requirements meetings
- Parse spreadsheets with requirement lists
- Consolidate into unified RESEARCH.md
Discovery Questions (7 Core Areas)
Interview stakeholders to fill gaps using seven categories:
1. Business Context (5 questions)
- What business problem does this solve?
- How will success be measured?
- Who are the primary users?
- What's the competitive landscape?
- What's the timeline and budget constraint?
2. Current State (5 questions)
- How are users currently solving this (if at all)?
- What pain points exist with current approach?
- What works well that should be preserved?
- How many users/transactions currently?
- What's acceptable downtime/SLA?
3. Technical Constraints (4 questions)
- Must integrate with specific systems? Which ones?
- Technology standards to follow?
- Performance targets (response time, throughput)?
- Data residency or infrastructure constraints?
4. Functional Scope (3 questions)
- What's in scope for MVP?
- What's explicitly out of scope?
- What's nice-to-have for future?
5. Non-Functional Requirements (4 questions)
- Availability target (99%, 99.9%, 99.99%)?
- Expected growth (users, data volume)?
- Compliance requirements (GDPR, HIPAA, SOC2)?
- Security sensitivity (public data vs confidential)?
6. Dependencies & Integrations (3 questions)
- What external services must integrate?
- Existing APIs to consume or expose?
- Data sharing agreements needed?
7. Organizational Context (3 questions)
- Who are decision makers and stakeholders?
- What organizational changes needed?
- Training and adoption plan?
Document all answers in RESEARCH.md.
Ecosystem Check
Map the project's external dependencies and integrations:
Outbound Integrations (services this system calls)
- Payment processor (Stripe, Square)
- Email service (SendGrid, AWS SES)
- Analytics (Mixpanel, Amplitude)
- Cloud services (AWS S3, Google Cloud Storage)
Inbound Integrations (services that call this system)
- Mobile apps consuming APIs
- Third-party reporting tools
- Legacy system migrations
- Partner integrations
Data Flow Map
- Source systems for data ingestion
- Destination systems for data export
- Real-time vs batch sync requirements
- Data transformation rules
Compliance Ecosystem
- Audit requirements and standards
- Data governance policies
- Breach notification procedures
- Vendor security assessment
Generate dependency graph and assess risk of each integration.
RESEARCH.md Format
Structure the research artifact as:
# Research Phase Report
**Project:** [name]
**Date:** [YYYY-MM-DD]
**Phase:** 1 - Research
**Status:** Complete
## Executive Summary
[1-paragraph overview of key findings]
## Greenfield vs Brownfield Assessment
**Classification:** [Greenfield | Brownfield]
[2-3 paragraphs explaining rationale]
## Technology Stack (Brownfield)
[Catalog of existing tech with versions]
### Current Performance Metrics
[Uptime, response times, throughput]
## Imported Documents
- [Document 1]: [Summary]
- [Document 2]: [Summary]
## Ecosystem Integrations
### Outbound
[List with brief description]
### Inbound
[List with brief description]
## Discovery Findings
[Answers to 7 discovery question categories]
## Risk Assessment
- Technical risks: [list with mitigation]
- Organizational risks: [list]
- External dependency risks: [list]
## Recommendations
[Next phase readiness assessment]
## Appendix: Full Tech Stack
[Detailed technology inventory]
Research Commands
/specky:research --greenfield # Start new project
/specky:research --brownfield # Analyze existing code
/specky:research --tech-scan # Technology stack only
/specky:research --import-docs # Document aggregation
/specky:research --discovery # Stakeholder interviews
MCP Tools
| Tool | Purpose |
|---|
sdd_scan_codebase | Detect language, framework, package manager, folder structure |
sdd_discover | Generate 7 structured discovery questions |
sdd_research | Investigate technical unknowns and produce findings |
sdd_import_document | Import PDF/DOCX/MD documents as research context |
sdd_import_transcript | Import VTT/SRT meeting transcripts |
sdd_batch_import | Batch import multiple documents |
sdd_check_ecosystem | Report recommended MCP server integrations |
Companion Agent
@research-analyst — Phase 1 agent that calls these tools to build the knowledge baseline. Load this skill as first step.
