docs: design analysis stall fix

docs/superpowers/specs/2026-06-18-analysis-stall-design.md

@@ -0,0 +1,43 @@
+# Analysis Stall Fix Design
+
+## Problem
+
+The summary analysis appears to stall after logging a matched WeChat issue. The
+analysis thread is still running, but it provides no progress while scanning
+rules or checking article URLs. Deleted-article checks are performed serially,
+with a 10-second timeout per unique URL. Repeated clicks can also start multiple
+analysis threads.
+
+## Design
+
+Keep the existing matching behavior and change only task execution and
+observability:
+
+- Check unique WeChat article URLs with a bounded pool of eight workers.
+- Limit each URL request to three seconds.
+- Treat timeout and network errors as "unknown" and retain the analysis result.
+- Cache each unique URL result so duplicate matches are checked once.
+- Report rule-scanning progress and URL-checking progress through a callback.
+- Forward progress messages from `AnaThread` to the existing log signal.
+- Disable the analysis button while work is active and restore it when the
+  thread finishes, including after exceptions.
+- Ignore attempts to start analysis while an existing analysis thread is
+  running.
+
+## Error Handling
+
+An unavailable article URL must not remove a finding. Only a successful response
+containing the existing deleted-content marker removes matching rows. Exceptions
+remain contained in the worker thread and are reported through the application
+log.
+
+## Testing
+
+Add unit tests that verify:
+
+- Duplicate URLs are fetched only once under concurrent execution.
+- Deleted rows are removed while normal and failed requests are retained.
+- Progress callbacks reach their final totals.
+- Analysis progress callbacks are emitted during rule scanning.
+
+Run the complete existing unit-test suite with the bundled Python runtime.