WeReadBoard/docs/superpowers/plans/2026-09-14-maintenance-debug-guide.md

Maintenance Debug Guide Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 建立可持续维护的日常排障文档，记录本次端口与 Python CA 证书故障。

Architecture: docs/troubleshooting.md 保存完整故障记录；README.md 和 docs/technical-guide.md 仅提供入口与同步维护要求。运行态只保留当前项目的 8080 服务。

Tech Stack: Markdown、Git、macOS/Linux 常用诊断命令

---

Task 1: 新增排障记录

Files:

• Create: docs/troubleshooting.md

• 记录故障现象、根因链路、诊断命令、恢复步骤和预防措施。

• 明确接口、端口、Python 环境或部署方式变化时同步更新本文档。

Task 2: 增加文档入口

Files:

• Modify: README.md

• Modify: docs/technical-guide.md

• 在 README 项目结构中加入排障文档。

• 在技术指南中增加日常维护与排障入口及维护约束。

Task 3: 验证并合并

Files:

• Verify: docs/troubleshooting.md

• Verify: README.md

• Verify: docs/technical-guide.md

• 检查文档链接与 Markdown 格式。

• 确认 8770 已关闭，8080 页面和状态接口返回 200。

• 提交专门分支，并使用 git merge --no-ff 合并到 dev。