[feat] Doc backfill, ticket-context DRY, Python language skill

README.md

@@ -26,10 +26,10 @@ cd swe-workbench
 
 ## What's inside
 
-- **Commands** — `/swe-workbench:review`, `/swe-workbench:design`, `/swe-workbench:refactor`, `/swe-workbench:debug`, `/swe-workbench:implement`, `/swe-workbench:test`, `/swe-workbench:security-review` — see [docs/catalog.md](docs/catalog.md).
-- **Subagents** — `reviewer`, `senior-engineer`, `refactorer`, `debugger`, `security-auditor`, `test-writer` — see [docs/catalog.md](docs/catalog.md).
+- **Commands** — `/swe-workbench:review`, `/swe-workbench:design`, `/swe-workbench:refactor`, `/swe-workbench:debug`, `/swe-workbench:implement`, `/swe-workbench:test`, `/swe-workbench:security-review`, `/swe-workbench:capture`, `/swe-workbench:cleanup-merged` — see [docs/catalog.md](docs/catalog.md).
+- **Subagents** — `reviewer`, `senior-engineer`, `refactorer`, `debugger`, `security-auditor`, `test-writer`, `product-manager` — see [docs/catalog.md](docs/catalog.md).
 - **Principles** — Clean Architecture, DDD, SOLID, TDD, design patterns, clean code, observability, API design, concurrency, error handling, security — auto-load by trigger keyword.
-- **Languages** — Go, Rust, TypeScript — auto-load by file extension.
+- **Languages** — Go, Rust, TypeScript, Python — auto-load by file extension.
 - **Integrations** — `ticket-context` — auto-loads on ticket references (Jira, Confluence, GitHub) to feed the full spec into commands.
 - **Workflows** — `development` orchestrator wrapping the full 5-phase implementation lifecycle.
 

commands/debug.md

@@ -5,7 +5,7 @@ argument-hint: <symptom, failing test, or error, optionally with a ticket ref>
 
 Symptom: $ARGUMENTS
 
-If $ARGUMENTS contains a ticket reference (Jira key like `PROJ-123`, an `atlassian.net` URL, a Confluence wiki URL, or a GitHub issue/PR URL or `#NNN`), invoke the `swe-workbench:ticket-context` skill first and prepend its structured summary to the delegation context below.
+If $ARGUMENTS contains a ticket reference, invoke `swe-workbench:ticket-context` first and prepend its structured summary to the delegation context below. (Trigger patterns are defined in that skill's "When to invoke" section.)
 
 Delegate to the `debugger` subagent. Its output must include:
 

commands/design.md

@@ -5,7 +5,7 @@ argument-hint: <design question>
 
 The user is asking: $ARGUMENTS
 
-If $ARGUMENTS contains a ticket reference (Jira key like `PROJ-123`, an `atlassian.net` URL, a Confluence wiki URL, or a GitHub issue/PR URL or `#NNN`), invoke the `swe-workbench:ticket-context` skill first and prepend its structured summary so the subagent has the full design brief.
+If $ARGUMENTS contains a ticket reference, invoke `swe-workbench:ticket-context` first and prepend its structured summary so the subagent has the full design brief. (Trigger patterns are defined in that skill's "When to invoke" section.)
 
 Delegate to the `senior-engineer` subagent. Its response must contain:
 

commands/implement.md

@@ -5,7 +5,7 @@ argument-hint: <ticket ref, GitHub issue URL, or feature description>
 
 Feature request: $ARGUMENTS
 
-If $ARGUMENTS contains a ticket reference (Jira key like `PROJ-123`, an `atlassian.net` URL, a Confluence wiki URL, or a GitHub issue/PR URL or `#NNN`), invoke the `swe-workbench:ticket-context` skill first and prepend its structured summary to the context below. Skip this prelude if $ARGUMENTS is free-text with no recognizable ref.
+If $ARGUMENTS contains a ticket reference, invoke `swe-workbench:ticket-context` first and prepend its structured summary to the context below. Skip if $ARGUMENTS is free-text with no recognizable ref. (Trigger patterns are defined in that skill's "When to invoke" section.)
 
 Activate the `swe-workbench:workflow-development` skill in **Mode B (Implementation-Time Behavior)**. Execute all five phases in order:
 

commands/refactor.md

@@ -5,7 +5,7 @@ argument-hint: <file, function, or module>
 
 Target: $ARGUMENTS
 
-If $ARGUMENTS contains a ticket reference (Jira key like `PROJ-123`, an `atlassian.net` URL, a Confluence wiki URL, or a GitHub issue/PR URL or `#NNN`), invoke the `swe-workbench:ticket-context` skill first; a refactor motivated by a ticket needs the ticket's scope and constraints in the delegation context.
+If $ARGUMENTS contains a ticket reference, invoke `swe-workbench:ticket-context` first — a refactor motivated by a ticket needs the ticket's scope and constraints in the delegation context. (Trigger patterns are defined in that skill's "When to invoke" section.)
 
 Delegate to the `refactorer` subagent. Its output must include:
 

commands/review.md

@@ -1,5 +1,6 @@
 ---
 description: Review the current git diff with senior-engineer depth — correctness, security, design, and test gaps
+argument-hint: "[ticket ref or leave blank to review current diff]"
 ---
 
 Review the pending changes on this branch.

commands/security-review.md

@@ -1,5 +1,6 @@
 ---
 description: Audit the current git diff for security vulnerabilities — OWASP Top 10, secrets, insecure APIs, dependency CVEs
+argument-hint: "[ticket ref or leave blank to audit current diff]"
 ---
 
 Audit the pending changes on this branch for security vulnerabilities.

commands/test.md

@@ -5,7 +5,7 @@ argument-hint: <file, function, or module>
 
 Target: $ARGUMENTS
 
-If $ARGUMENTS contains a ticket reference (Jira key like `PROJ-123`, an `atlassian.net` URL, a Confluence wiki URL, or a GitHub issue/PR URL or `#NNN`), invoke the `swe-workbench:ticket-context` skill first; tests motivated by a ticket need the ticket's acceptance criteria in the delegation context.
+If $ARGUMENTS contains a ticket reference, invoke `swe-workbench:ticket-context` first — tests motivated by a ticket need the ticket's acceptance criteria in the delegation context. (Trigger patterns are defined in that skill's "When to invoke" section.)
 
 Delegate to the `test-writer` subagent. Its output must include:
 

docs/catalog.md

@@ -11,6 +11,7 @@
 | `/swe-workbench:debug <symptom>` | Diagnose a bug or failing test via systematic-debugging, then minimal fix + regression test. |
 | `/swe-workbench:test <target>` | Write focused, behavioural tests in the target language's idiom. |
 | `/swe-workbench:implement <ticket or description>` | Drive a feature end-to-end — branch, plan, TDD build, verify, review, PR. Orchestrates the full 5-phase `workflow-development` lifecycle. |
+| `/swe-workbench:capture <one-line thought>` | Capture an idea, bug, or improvement as a well-framed GitHub issue via the `product-manager` subagent. Auth + repo detection, product framing, duplicate scan, draft preview, and user-confirm gate before filing. |
 | `/swe-workbench:cleanup-merged [PR number]` | Remove the worktree, local branch, and remote branch for a merged PR. Defaults to the current branch. Squash-merge safe. |
 
 ## Subagents
@@ -23,6 +24,7 @@
 | `refactorer` | Cleaning up smells before adding a feature. |
 | `debugger` | Bug diagnosis and minimal fix — composes `superpowers:systematic-debugging`, layers principle lens. |
 | `test-writer` | Authoring tests for an existing function, module, or change set. |
+| `product-manager` | Drafts a well-framed GitHub issue from a raw idea — product framing (problem, value, RICE-lite), template detection, duplicate scan, and confirm gate. Invoked by `/swe-workbench:capture`. |
 
 ## Skills
 
@@ -49,6 +51,7 @@
 | `language-go` | `.go` files, `go.mod`, `go.sum`, keywords: Go, Golang, goroutine, channel, context. |
 | `language-rust` | `.rs` files, `Cargo.toml`, keywords: Rust, cargo, ownership, borrow checker, trait, lifetime. |
 | `language-typescript` | `.ts`, `.tsx`, `.js`, `.jsx`, `package.json`, keywords: TypeScript, Node, tsconfig. |
+| `language-python` | `.py` files, `pyproject.toml`, `requirements.txt`, keywords: Python, pytest, asyncio, dataclass, type hints, virtualenv. |
 
 ### Workflows — auto-load during implementation
 

skills/language-python/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: language-python
+description: Python idioms — PEP 8, type hints, dataclasses, context managers, generators, asyncio, and testing. Auto-load when working with .py files, pyproject.toml, requirements.txt, or when the user mentions Python, pytest, asyncio, dataclass, type hints, or virtualenv.
+---
+
+# Python
+
+## Type hints
+- Annotate all function signatures; `Any` is a smell unless at a genuine boundary.
+- Use `dataclass` for data containers with behavior; `TypedDict` for dict-shaped data at boundaries.
+- Prefer `Protocol` over ABC when duck typing suffices — no inheritance required.
+- `from __future__ import annotations` for forward refs in 3.9 and earlier.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class Order:
+    id: str
+    items: list[str] = field(default_factory=list)
+    total: float = 0.0
+```
+
+## Errors and exceptions
+- Use exceptions for exceptional paths, not flow control.
+- Raise specific subclasses; catch the narrowest class you can handle.
+- `except Exception:` is almost always wrong — at minimum log and re-raise.
+- `contextlib.suppress(SomeError)` for intentional ignore; bare `except:` never.
+
+```python
+try:
+    result = load(path)
+except FileNotFoundError:
+    raise MissingConfigError(path) from None
+```
+
+## Context managers
+- `with` for any resource with a cleanup obligation: files, locks, DB connections.
+- `@contextlib.contextmanager` for ad-hoc managers without a full class.
+- Never hold a resource longer than the `with` block.
+
+```python
+@contextlib.contextmanager
+def managed_resource():
+    r = acquire()
+    try:
+        yield r
+    finally:
+        release(r)
+```
+
+## Generators and iterators
+- Prefer generators over materializing full lists when you only iterate once.
+- `yield from` to delegate to sub-generators.
+- Reach for `itertools` before writing loops: `chain`, `islice`, `groupby`, `product`.
+
+```python
+def read_chunks(path: Path, size: int = 4096):
+    with open(path, "rb") as f:
+        while chunk := f.read(size):  # walrus operator, 3.8+
+            yield chunk
+```
+
+## Concurrency
+- **GIL caveat:** threads don't parallelize CPU-bound work — use `ProcessPoolExecutor` or `multiprocessing`.
+- `asyncio` for IO-bound concurrency; `asyncio.TaskGroup` (3.11+) for structured fan-out.
+- `ThreadPoolExecutor` for legacy sync IO or blocking C extensions.
+- One event loop per process; never nest or mix loops.
+
+```python
+async def fetch_all(urls: list[str]) -> list[str]:
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(fetch(u)) for u in urls]
+    return [t.result() for t in tasks]
+```
+
+## Pattern matching (3.10+)
+Use `match` for structural dispatch on data shapes; avoid it as a glorified `if/elif` chain.
+
+```python
+match command:
+    case {"action": "move", "direction": dir}:
+        move(dir)
+    case {"action": "quit"}:
+        quit()
+    case _:
+        raise ValueError(f"unknown command: {command}")
+```
+
+## Dependencies and packaging
+- `pyproject.toml` is the standard — no `setup.py` in new projects.
+- `uv` for fast installs; `poetry` for lockfile publishing workflows.
+- Pin transitive deps via lockfile (`uv.lock`, `poetry.lock`) in applications; use version ranges in libraries.
+- Always isolate with a virtualenv — never install into the system Python.
+
+## Testing
+- `pytest` over `unittest` — fixtures, parametrize, and plugins make it richer.
+- `@pytest.mark.parametrize` instead of loops inside tests.
+- `unittest.mock.patch` for external boundaries only; don't mock internals.
+- `pytest-asyncio` for async tests; `respx` or `httpx` mock transport for HTTP clients.
+
+```python
+@pytest.mark.parametrize("a, b, expected", [(1, 2, 3), (0, 0, 0)])
+def test_add(a, b, expected):
+    assert add(a, b) == expected
+```
+
+## Performance
+- Profile before optimizing: `cProfile` for CPU hotspots, `tracemalloc` for memory.
+- `py-spy` samples live processes without code changes.
+- C extensions (`cffi`, `Cython`) only after profiling confirms a Python bottleneck.
+- Cache attribute lookups in tight loops: `fn = obj.method` outside the loop.
+
+## Avoid
+- Mutable default arguments (`def f(x=[])` — use `None`, assign inside).
+- `from module import *` — pollutes namespace, breaks static analysis.
+- `global` / `nonlocal` except in narrow closures.
+- Broad `try/except` blocks that swallow errors silently.
+- `subprocess.run(shell=True)` with user-controlled input — use the list form.
+- Reimplementing what `itertools`, `functools`, or `collections` already provide.