Good First Issues

Curated list of approachable tasks for new contributors. Each one is self-contained and can be completed without deep knowledge of the full system.

#	Title	Difficulty	Relevant Files	Description	Suggested Approach
1	Add docstrings to AuditLog class and its methods	Easy	superpowers/audit.py	The AuditLog class and all 4 public methods (log, tail, search, path) lack docstrings. The coding standard requires Google-style docstrings on all public APIs.	Read the method signatures and the existing tests in tests/test_audit.py to understand behavior, then add docstrings.
2	Add docstrings to BrowserEngine class (16 methods)	Medium	superpowers/browser/engine.py	BrowserEngine and all its public methods (start, stop, goto, screenshot, extract_text, fill_form, etc.) are missing docstrings.	Each method is short. Read the code and add a one-liner plus Args/Returns where applicable.
3	Add docstrings to CredentialRotationChecker and related dataclasses	Easy	superpowers/credential_rotation.py	Four classes (AlertStatus, CredentialAlert, RotationPolicy, CredentialRotationChecker) and 5 methods missing docstrings.	Dataclasses just need a class-level docstring explaining their purpose.
4	Add docstrings to memory subsystem	Easy	superpowers/memory/store.py, superpowers/memory/base.py, superpowers/memory/context.py	The MemoryStore methods (remember, recall, search, forget, list_memories, decay, stats) and base dataclasses lack docstrings.	Check tests/test_memory_store.py for usage patterns.
5	Add docstrings to WatcherEngine class	Easy	superpowers/watcher/engine.py	WatcherEngine and 5 public methods (start, stop, list_rules, get_rule, on_any_event) need docstrings.	Short class, each method is straightforward.
6	Add docstrings to ProfileManager and browser dataclasses	Easy	superpowers/browser/profiles.py, superpowers/browser/base.py	ProfileManager (3 methods) and 3 dataclasses (BrowserConfig, PageResult, ElementData) lack docstrings.	Small file, quick task.
7	Write tests for config.py	Medium	superpowers/config.py, tests/	The config loader module has no dedicated test file. It handles .env loading and default paths.	Create tests/test_config.py with tests for default paths, env var overrides, and missing .env handling.
8	Write tests for telegram_notify.py	Medium	superpowers/telegram_notify.py, tests/	The Telegram notification helper has no test file. It wraps HTTP calls to the Telegram Bot API.	Create tests/test_telegram_notify.py, mock HTTP calls with unittest.mock.patch, test success and error paths.
9	Write tests for skill_loader.py	Medium	superpowers/skill_loader.py, tests/	The skill loader (discovers and runs skills) has no dedicated test file despite being a core component.	Create tests/test_skill_loader.py. Test skill discovery, YAML parsing, sandboxed execution. Mock subprocess calls.
10	Replace except BaseException with specific exceptions in atomic-write patterns	Easy	superpowers/cron_engine.py:444, superpowers/ssh_fabric/health.py:123, superpowers/vault.py:165	Three files use except BaseException: in their atomic-write cleanup blocks. These should catch BaseException intentionally (to clean up temp files) but should be annotated with # noqa comments explaining why, or narrowed where possible.	Add # noqa: BLE001 -- cleanup temp file on any failure comments, or refactor to use contextlib.suppress / finally blocks.
11	Add --help descriptions to CLI subcommands missing them	Easy	superpowers/cli_cron.py, superpowers/cli_ssh.py, superpowers/cli_vault.py	Several Click command groups and subcommands lack help= strings, so claw <cmd> --help shows no description.	Search for @click.command() and @click.group() calls without help= parameter and add concise descriptions.
12	Add extended descriptions to skill.yaml manifests	Easy	skills/*/skill.yaml	Most skill manifests have only a single description: line. Adding a long_description: or multi-line description would improve claw skill list --verbose output.	Pick 3-5 skills, read their run.py/run.sh, and expand the YAML description with usage examples and what the skill checks.
13	Add .env.example completeness check	Easy	.env.example, superpowers/config.py	The .env.example documents some variables but may drift from what the code actually reads. A test or script that ensures every os.getenv() / os.environ[] call in the codebase has a corresponding entry in .env.example would prevent configuration drift.	Grep for os.getenv and os.environ across the codebase, compare keys to .env.example, write a test that fails on missing entries.
14	Create a claw doctor diagnostic command	Medium	superpowers/cli.py	There is no single command to check that the environment is healthy (Python version, venv active, Redis reachable, Docker running, age installed). A claw doctor command would help new users troubleshoot setup.	Add a doctor subcommand that checks prerequisites and prints a pass/fail table. See skills/heartbeat/ for a similar pattern.
15	Add retry logic to skill_creator.py template generation	Easy	superpowers/skill_creator.py	The skill creator has 3 TODO comments (# TODO: implement skill logic, # TODO: add arguments, # TODO: implement skill logic) in its generated template code. These should be replaced with more helpful scaffold code or at minimum better placeholder comments.	Replace the TODOs with meaningful placeholder implementations (e.g., argparse boilerplate, a sample main() body, example print statements).
16	Add type hints to SkillHub class	Easy	superpowers/skillhub.py	The SkillHub class and SyncResult dataclass are missing docstrings. Several methods could benefit from more precise type annotations (e.g., return types on sync methods).	Add docstrings and verify/add return type hints to all public methods.
17	Write a smoke test for each skill	Medium	skills/*/run.py, skills/*/run.sh, tests/	Most skills lack even a basic "does it import / parse args without crashing" test. A parametrized pytest that discovers all skills and runs --help (or imports the module) would catch import errors early.	Create tests/test_skills_smoke.py that globs skills/*/skill.yaml, imports or invokes each skill's entry point with --help, and asserts exit code 0.