tech-stack-research

name	tech-stack-research
version	1.0.0
description	[Architecture] Use when you need to research, analyze, and compare tech stack options as a solution architect.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Deliver a user-confirmed, per-layer tech stack — each choice backed by 3+ researched options, weighted scoring, cited evidence, and a confidence % — by acting as a solution architect who derives technical requirements from business analysis, researches the current market, and produces a detailed comparison report, so the team commits to a stack fit for scale, budget, skills, and timeline, not familiarity.

Summary:

• Requirements come BEFORE research: load prior business/domain/PBI artifacts, map business signals to technical requirements, and gate on user confirmation (AskUserQuestion) before any WebSearch.
• Evaluate every stack layer (backend, frontend, database, messaging, infra, auth) independently — minimum 3 WebSearched options per layer, each with cited evidence (URL, benchmark, case study), never familiarity.
• Score with the weighted 8-criteria matrix (High=3x / Medium=2x / Low=1x), then rank each layer with a confidence %; capped <=200-line report goes to {plan-dir}/research/tech-stack-comparison.md.
• The end-of-skill user validation interview (5-8 questions) is mandatory and never skipped — only confirmed decisions get written to phase-02-tech-stack.md as status: confirmed.

Workflow:

1. Load Business Context — Read business evaluation, domain model, refined PBI artifacts
2. Derive Technical Requirements — Map business needs to technical constraints
3. Research Per Layer — WebSearch top 3 options for each stack responsibility
4. Deep Compare — Pros/cons matrix, benchmarks, community health, team fit
5. Score & Rank — Weighted scoring across 8 criteria
6. Generate Report — Structured comparison report with recommendation
7. User Validation — Present findings, ask 5-8 questions, confirm choices

Key Rules:

• MANDATORY IMPORTANT MUST ATTENTION research minimum 3 options per stack layer
• MANDATORY IMPORTANT MUST ATTENTION include confidence % with evidence for every recommendation
• MANDATORY IMPORTANT MUST ATTENTION run user validation interview at end (never skip)
• All claims must cite sources (URL, benchmark, case study)
• Recommend based on benchmarked evidence (URL, benchmark, case study); never on familiarity alone

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Step 1: Load Business Context

Read artifacts from prior workflow steps (search in plans/ and team-artifacts/):

• Business evaluation report (viability, scale, constraints)
• Domain model / ERD (complexity, entity count, relationships)
• Refined PBI (acceptance criteria, scope)
• Discovery interview notes (team skills, budget, timeline)

Extract and summarize:

Signal	Value	Source
Expected users	...	discovery interview
Domain complexity	Low/Med/High	domain model
Team skills	...	discovery interview
Budget constraint	...	business evaluation
Timeline	...	business evaluation
Compliance needs	...	business evaluation
Real-time needs	Yes/No	refined PBI
Integration complexity	Low/Med/High	domain model

Step 2: Derive Technical Requirements

Map business signals to technical requirements:

Business Signal	Technical Requirement	Priority
High user scale	Horizontal scaling, connection pooling	Must
Complex domain	Strong type system, ORM with migrations	Must
Real-time features	WebSocket/SSE support, event-driven arch	Must
Small team	Low learning curve, good DX, batteries-included	Should
Tight budget	Open-source, low hosting cost	Should
Compliance	Audit trail, encryption, auth framework	Must

MANDATORY IMPORTANT MUST ATTENTION validate derived requirements with user via AskUserQuestion before proceeding to research.

Step 3: Research Per Stack Layer

For EACH layer, research top 3 options using WebSearch (minimum 5 queries total):

Stack Layers to Evaluate

Layer	Example Options	Research Focus
Backend Framework	Candidate backend runtimes/frameworks	Performance, type safety, ecosystem
Frontend Framework	Candidate frontend frameworks	DX, ecosystem, hiring, enterprise fit
Database	Candidate database engines/stores	Scale, query complexity, cost
Messaging/Events	Candidate messaging/event systems	Throughput, reliability, complexity
Infrastructure	Docker+K8s, Serverless, PaaS	Cost, ops overhead, scaling
Auth	Keycloak, Auth0, custom	Cost, compliance, flexibility

WebSearch Queries (minimum 5 per layer)

"{option_A} vs {option_B} {current_year} comparison"
"{option} enterprise production case studies"
"{option} community size github stars"
"{option} performance benchmarks {use_case}"
"{option} security track record vulnerabilities"

Step 4: Deep Comparison Matrix

For EACH stack layer, produce a comparison table:

Criteria	Option A	Option B	Option C	Weight
Team Fit	score + rationale	...	...	High
Scalability	score + rationale	...	...	High
Time-to-Market	score + rationale	...	...	High
Ecosystem/Libs	score + rationale	...	...	Medium
Hiring Market	score + rationale	...	...	Medium
Cost (hosting)	score + rationale	...	...	Medium
Learning Curve	score + rationale	...	...	Medium
Community Health	score + rationale	...	...	Low

Scoring: 1-5 scale. Weight: High=3x, Medium=2x, Low=1x.

Per-Option Detail Block

For each option, document:

### {Layer}: {Option Name}

**Pros:**

- {Pro 1} — {evidence/source}
- {Pro 2} — {evidence/source}
- {Pro 3} — {evidence/source}

**Cons:**

- {Con 1} — {evidence/source}
- {Con 2} — {evidence/source}

**Best suited when:** {conditions}
**Not suitable when:** {conditions}
**Production examples:** {2-3 real companies using this}

Step 5: Weighted Score & Ranking

Calculate weighted total per option per layer. Present ranking:

### {Layer} Ranking

1. **{Option A}** — Score: {X}/100 — Confidence: {Y}%
2. **{Option B}** — Score: {X}/100 — Confidence: {Y}%
3. **{Option C}** — Score: {X}/100 — Confidence: {Y}%

**Recommendation:** {Option A}
**Why:** {2-3 sentence rationale linking to team skills, scale, and constraints}

Step 6: Generate Report

Write report to {plan-dir}/research/tech-stack-comparison.md with:

1. Executive summary (recommended full stack in 5 lines)
2. Technical requirements table (from Step 2)
3. Per-layer comparison matrices (from Step 4)
4. Per-layer rankings with recommendations (from Step 5)
5. Combined recommended stack diagram
6. Risk assessment for recommended stack
7. Alternative stack (second-best combo) for comparison
8. Unresolved questions

Report must be <=200 lines. Use tables over prose.

Step 7: User Validation Interview

MANDATORY IMPORTANT MUST ATTENTION present findings and ask 5-8 questions via AskUserQuestion:

Required Questions

1. Per-layer recommendation confirmation — "For {layer}, I recommend {option}. Agree?"
   • Options: Agree (Recommended) | Prefer {option B} | Need more research
2. Risk tolerance — "The recommended stack has {risk}. Acceptable?"
3. Team readiness — "Team needs to learn {X}. Training plan needed?"
4. Budget alignment — "Estimated infra cost: ${X}/month. Within budget?"
5. Timeline fit — "This stack enables MVP in {X} months. Acceptable?"

Optional Deep-Dive Questions (pick 2-3 based on context)

• "Should we consider {emerging tech} for {layer}?"
• "Any compliance requirements I haven't captured?"
• "Preference for managed services vs self-hosted?"
• "Monorepo or polyrepo for this team size?"

After user confirms, update report with final decisions and mark as status: confirmed.

Output

{plan-dir}/research/tech-stack-comparison.md    # Full comparison report
{plan-dir}/phase-02-tech-stack.md               # Final confirmed tech stack decisions

---

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate EVERY recommendation with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION include confidence % and evidence citations for all claims. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality.

---

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "/architecture-design (Recommended)" — Design solution architecture with chosen tech stack
• "/plan" — If architecture already decided
• "Skip, continue manually" — user decides

Council escalation (always-offer, second prompt)

After the existing ## Next Steps prompt above resolves, present a second, independent AskUserQuestion call:

• "Skip council — proceed with chosen stack (Recommended)" — Continue with the selected tech stack as-is.
• "Escalate to /llm-council" — Run 11 sub-agent council. Best applied when 2+ stacks score within 15% on the comparison matrix or you have unfamiliar/strategic dependencies. Cheaper alternatives: /why-review, /plan-validate.

Prompt-Enhance Closing Anchors

• IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
• IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
• IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
• IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

Closing Reminders

IMPORTANT MUST ATTENTION Goal: deliver user-confirmed, per-layer tech stack — each choice backed by 3+ researched options, weighted 8-criteria scoring, cited evidence, confidence % — so team commits to a stack fit for scale, budget, skills, timeline, NOT familiarity.

Protocols in force (concise digest of the SYNC/shared blocks this skill carries):

• Critical Thinking: MUST ATTENTION apply critical + sequential thinking; traced proof, confidence >80% to act, NEVER guess as fact.
• AI Mistake Prevention: verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.

IMPORTANT MUST ATTENTION research minimum 3 WebSearched options per stack layer (backend, frontend, database, messaging, infra, auth); every recommendation carries confidence % + cited evidence (URL, benchmark, case study) — NEVER recommend on familiarity alone — why: familiarity bias commits the team to the wrong stack that surfaces only at scale. IMPORTANT MUST ATTENTION gate on user via AskUserQuestion at EVERY decision point — confirm derived requirements before research (Step 2), confirm each layer recommendation in the end interview (Step 7) — NEVER auto-decide — why: the team owns the stack, not the AI. MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting; mark one in_progress, completed immediately after evidence; add a final review todo.

MUST ATTENTION apply critical + sequential thinking — every claim needs appropriate traced evidence (file:line for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.

MUST ATTENTION apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task:

Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting. Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect. Assume existing values are intentional — ask WHY before changing. Before changing a constant, limit, flag, wording, or pattern, read nearby context and history. Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk. Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.

IMPORTANT MUST ATTENTION requirements come BEFORE research — load prior business/domain/PBI artifacts (Step 1), map business signals to technical requirements (Step 2), user-confirm them, THEN WebSearch (Step 3) — NEVER research before requirements are derived and confirmed — why: researching first picks tech then back-fits the problem, the reverse of architecture. IMPORTANT MUST ATTENTION score every layer with the weighted 8-criteria matrix (High=3x / Medium=2x / Low=1x), rank with confidence %, cap the {plan-dir}/research/tech-stack-comparison.md report at <=200 lines using tables over prose — why: an unscored or unbounded report hides the trade-off the decision turns on. IMPORTANT MUST ATTENTION only user-confirmed decisions get written to phase-02-tech-stack.md as status: confirmed — the end interview (5-8 AskUserQuestion questions) is mandatory and never skipped even when the choice seems "obvious" — why: an unconfirmed stack is a guess the team will pay for. IMPORTANT MUST ATTENTION every claim, finding, and recommendation requires file:line/URL proof or traced evidence + confidence % (>80% act, 60-80% verify first, <60% DO NOT recommend) — NEVER present a guess as fact — why: a stack chosen on speculation fails silently until production. IMPORTANT MUST ATTENTION evaluate fit before copying a reference stack from another project — verify the new context shares the same scale, budget, team skills, compliance, and timeline constraints — why: the closest example rarely matches preconditions, and a mismatched copy compiles but fails the real requirements.

Anti-Rationalization:

Evasion	Rebuttal
"Stack is obvious — skip the research"	3+ WebSearched options per layer with cited evidence anyway — familiarity is not evidence.
"I already know this is the best framework"	Show the weighted 8-criteria score + confidence %. No matrix = no recommendation.
"Skip the user interview, the choice is clear"	The end interview is MANDATORY — only status: confirmed decisions get written.
"Just research the stack, requirements are fine"	Derive + user-confirm technical requirements FIRST (Steps 1-2), then research.
"One source is enough for this layer"	Cite URL + benchmark + case study; a single anecdote is not benchmarked evidence.

External Memory: For research/analysis work, write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, recommendation requires file:line/URL proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).