# Pitfall Log

Project: nano-step/nano-brain

Summary: Found 30 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Interactive MCP client auto-configuration after workspace registration
- User impact: Developers may fail before the first successful local run: Interactive MCP client auto-configuration after workspace registration
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/525

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v2026.7.0303
- User impact: Upgrade or migration may change expected behavior: v2026.7.0303
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0303

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/535

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/525

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/523

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/520

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/nano-step/nano-brain

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints
- User impact: Developers may misconfigure credentials, environment, or host setup: Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/530

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale
- User impact: Developers may misconfigure credentials, environment, or host setup: CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/527

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: MCP: bind default workspace via URL query param, skip agent-side discovery
- User impact: Developers may misconfigure credentials, environment, or host setup: MCP: bind default workspace via URL query param, skip agent-side discovery
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/523, failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/522

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v2026.7.0103
- User impact: Upgrade or migration may change expected behavior: v2026.7.0103
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0103

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v2026.7.0302
- User impact: Upgrade or migration may change expected behavior: v2026.7.0302
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0302

## 13. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/nano-step/nano-brain

## 14. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read
- User impact: Developers may hit a documented source-backed failure mode: Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/529

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nano-step/nano-brain

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/nano-step/nano-brain

## 17. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/nano-step/nano-brain

## 18. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/530

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/529

## 20. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/nano-step/nano-brain/issues/527

## 21. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: watcher: gate code-summarize notify on files that actually yield symbols
- User impact: Developers may hit a documented source-backed failure mode: watcher: gate code-summarize notify on files that actually yield symbols
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/520

## 22. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement hook
- User impact: Developers may hit a documented source-backed failure mode: Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement hook
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/536

## 23. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents
- User impact: Developers may hit a documented source-backed failure mode: Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents
- Evidence: failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/535

## 24. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nano-step/nano-brain

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/nano-step/nano-brain

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v2026.7.0102
- User impact: Upgrade or migration may change expected behavior: v2026.7.0102
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0102

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v2026.7.0104
- User impact: Upgrade or migration may change expected behavior: v2026.7.0104
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0104

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v2026.7.0201
- User impact: Upgrade or migration may change expected behavior: v2026.7.0201
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0201

## 29. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v2026.7.0301
- User impact: Upgrade or migration may change expected behavior: v2026.7.0301
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0301

## 30. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v2026.7.0601
- User impact: Upgrade or migration may change expected behavior: v2026.7.0601
- Evidence: failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0601