From deep-thought
Turn brainstorm decisions into user stories, architecture doc, and ADRs. Use after brainstorming to define WHAT to build and HOW it fits together. Standalone or pipeline-aware via env vars. Triggers: architect, stories, architecture, design, ADR, define stories, write stories.
How this skill is triggered — by the user, by Claude, or both
Slash command
/deep-thought:architectThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn decisions into stories + architecture. Answers **WHAT to build** and **HOW it fits together** — the bridge between brainstorm and implementation.
Turn decisions into stories + architecture. Answers WHAT to build and HOW it fits together — the bridge between brainstorm and implementation.
This skill MAY: research (read-only), analyze codebase patterns, write stories and architecture docs. This skill MAY NOT: edit code, create source files, run tests, deploy, implement anything.
NEVER write code during this skill. Design and document only.
| Shortcut | Why It Fails | The Cost |
|---|---|---|
| "Skip codebase research — I know the patterns" | Your mental model may not match the actual codebase | Architecture conflicts with existing code → rework |
| "Write vague stories — the implementer will figure it out" | Vague stories produce vague implementations | Ambiguity → wrong code → rework |
| "Skip ADRs — the decision is obvious" | Obvious now, forgotten in 2 weeks | Decision gets reversed without understanding tradeoffs |
| "One big story — splitting is overhead" | Big stories hide complexity and block parallel work | Unestimable, unreviewable, unshippable |
Entry: User wants to define stories and architecture for a feature.
If $BRAINSTORM_PATH is set (pipeline mode):
$BRAINSTORM_PATHIf no env var (standalone mode):
docs/brainstorms/ for a recent match (last 14 days)Exit: Feature context understood — decisions extracted or gathered from user.
Entry: Feature context loaded.
Launch research via Agent:
Surface findings:
>> Existing pattern: src/services/auth.ts (similar service structure)
>> Convention: tests live alongside source as *.test.ts
>> Integration: uses EventBus for cross-module communication
Exit: Codebase patterns known, integration points identified.
Entry: Research complete.
Check the project's CLAUDE.md for a "Toolkit Output Paths" table. Use those paths if present, otherwise use defaults.
Output path: {stories_path}/{slug}.md
(Default stories_path: docs/stories/)
If $FEATURE_ID is set: use it as the slug. Otherwise derive from the feature description.
Each story follows this structure:
# {Feature Title}
## STORY-001: {Story title}
**As a** {actor}
**I want** {capability}
**So that** {value}
### Acceptance Criteria
- [ ] {Measurable, testable criterion}
- [ ] {Another criterion}
### Edge Cases
- {Edge case and expected behavior}
### Notes
- [INTEGRATION] {Integration point with existing system}
Story writing rules:
[INTEGRATION] tags mark where the story touches existing systemsExit: Stories file written with all stories, acceptance criteria, and edge cases.
Entry: Stories written.
Output path: {stories_path}/{slug}.architecture.md
Use the template from architecture-template.md in this skill's directory. The doc includes:
1. Requirements
2. Architecture Decision Records (ADRs)
adr-format.md)3. Dependencies
4. Integration Pattern
5. File Structure
6. External Services
7. Security Considerations
Exit: Architecture doc written alongside stories.
Entry: Stories and architecture doc written.
If interactive (no $BRAINSTORM_PATH):
Use AskUserQuestion with:
If user selects "Visualize / Share": Run /babel-fish:visualize {stories_path}/{slug}.architecture.md and try the shareable HTML flow first when share-html is configured. Otherwise render the terminal mind map. After rendering or sharing, return to this handoff with the remaining options.
If pipeline mode ($BRAINSTORM_PATH set):
Complete without asking. Output paths for downstream consumers:
Stories: {stories_path}/{slug}.md
Architecture: {stories_path}/{slug}.architecture.md
Before delivering, verify:
./architecture-template.md — Full architecture doc template./adr-format.md — ADR structure reference./story-format.md — Story format with examples../knowledge/strategic-decomposition.md — How to break work into units../knowledge/decision-frameworks.md — How to evaluate tradeoffsnpx claudepluginhub ondrej-svec/heart-of-gold-toolkit --plugin deep-thoughtGuides architecture design via Socratic questioning, generates technical docs like overview.md, domain-model.md, and ADR for new features, systems, or project structuring.
Creates ADRs in MADR format, arc42 documentation, and plan-context.md for architecture proposals. Handles branch verification, GitHub issue/PR creation, artifact triage, and backlog updates.
Generates a Software Architecture Document (Arc42 12 sections + C4 L1/L2) and ADRs for a feature, given an existing spec and glossary. Useful for tech leads and architects during feature design.