Hunt Bugs

cdkd Bug Hunt

Find latent cdkd bugs the way real users hit them: write a small CDK app using a resource / config / CFn notation cdkd has not exercised yet, deploy it to real AWS, and watch what breaks — on deploy AND destroy. Reading the source finds suspected bugs; deploying finds real ones. Exploratory and possibly expensive, acceptable only because every deployed resource is destroyed and verified gone ("Cleanup is non-negotiable" below).

Core principles

1. Many-people-hit beats niche. Prioritize daily CDK patterns (S3→Lambda notifications, BucketDeployment, Lambda logRetention, AwsCustomResource, LambdaRestApi, adding a GSI / changing a property on redeploy, grant* IAM, cross-stack refs) over exotic edge cases.
2. UPDATE and DESTROY are where bugs hide. CREATE usually works; the high-value paths are redeploy-with-a-changed-property (replacement classification, silent drops) and delete (custom-resource onDelete, ordering, state cleanup). Always test an update and always run destroy.
3. Check coverage first — hunt in genuinely-uncovered territory:

   grep -rln "BucketDeployment\|addEventNotification\|logRetention\|AwsCustomResource\|LambdaRestApi\|NodejsFunction" tests/integration/

4. Parallelize, but cap at ~4-5 in flight. One CDK app, several stacks. Pre-synth once, then deploy from the assembly — parallel deploys that each re-synth collide on the shared cdk.out lock. npx cdk synth --all -q once, then node dist/cli.js deploy <Stack> -a /tmp/cdkd-bughunt/cdk.out ... per stack. (Without -a, deploy serially.)

Workflow

1. Pick targets

Use the area hint, else 3-5 common-but-untested patterns. Favor cheap, fast resources (S3 / SSM / IAM / Lambda / DynamoDB / SNS / SQS / Logs / Events / API GW); run slow ones (RDS / ElastiCache / CloudFront) sparingly.

2. Scaffold a throwaway app

vp run build first (the CLI runs from dist/). One CDK app under /tmp/cdkd-bughunt/, one stack per pattern, names prefixed CdkdBughunt<Pattern>. pnpm install --ignore-workspace, then npx cdk synth --all -q. State bucket: cdkd-state-$(aws sts get-caller-identity --query Account --output text). Record every stack you are about to deploy into the bug-hunt sentinel (this arms the cleanup gate):

.claude/skills/hunt-bugs/bughunt-track.sh add CdkdBughuntS3Notify CdkdBughuntBucketDeploy ...

3. Deploy (parallel, capped)

node dist/cli.js deploy <Stack> -a <path-to-cdk.out> --state-bucket <bucket>, each to its own log. Watch for deploy errors, wrong replacement decisions, silent drops, custom-resource hangs. Where cheap, add a quick functional check (put an S3 object, confirm the notification fired) — a clean deploy summary is not proof the feature works.

4. Test an UPDATE

For at least one stack, redeploy with a changed property (env var, memory, GSI, tag, added resource). cdkd diff first, then deploy. The single richest bug source — verify the change reached AWS and was NOT a surprise replacement.

5. Destroy + verify zero orphans — non-negotiable

Destroy every stack (node dist/cli.js destroy <Stack> --state-bucket <bucket> --force), verify nothing leaked, then clear the sentinel:

# state-side: no CdkdBughunt* state.json (deployments/*.jsonl legitimately survives)
aws s3 ls s3://<bucket>/cdkd/ | grep -i bughunt
# resource-side: sweep by the CdkdBughunt naming (Lambdas, tables, buckets,
# roles, log groups, SSM params)
.claude/skills/hunt-bugs/bughunt-track.sh verify   # asserts each tracked stack's state.json is gone
.claude/skills/hunt-bugs/bughunt-track.sh clear    # only after orphan-zero

If destroy failed or left orphans, delete them by direct AWS API call before doing anything else.

6. On a confirmed bug: file an issue, then fix it — with a unit test

Always file a GitHub issue for every confirmed bug, even when fixing it in the same session — every bug becomes a tracked, claimable unit. An issue-only hunt round files the issue and stops there; a fix-in-session round still files it, then closes it from the PR (Closes #<n>). The body carries the real repro (the CDK app / commands / the exact deploy-update-destroy sequence).

Every issue carries the four classification lines (named in AGENTS.md -> Reporting; the scales are in ../../rules/session-report.md, which never auto-loads — its paths: glob matches only AGENTS.md, injected rather than read — so open it here), with Severity / Effort ALSO as labels (--label severity:<v> --label effort:<v>): the label workflow applies a missing one, so write them yourself, and the fix PR inherits them — never hand-add. Filing shapes and the mint-vs-fold decision are in ../work-issues/references/filing.md. A hunt is the best moment for the four lines: Severity is measured against real AWS rather than guessed, and you already know which fixture the fix will drag.

When you then WORK an issue — this hunt's own or one already filed — run /work-issues and follow it (its §0 screens untrusted comments; its §4 claims the issue BEFORE the first edit). Then fix:

1. Root-cause it in src/ (replacement-rules, the provider's create/update/delete, the diff calculator, the DAG, the intrinsic resolver).
2. Fix it in a lane tree, never in the main tree. Which tree depends on the launch mode — run the probe in .claude/skills/work-issues/references/launch-mode.md, never re-implement it. MAIN-CHECKOUT: git worktree add .claude/worktrees/<branch> -b <branch> origin/main. IN-PLACE: create no worktree (nesting dies with the outer workspace) but DO branch in place off origin/main; record the branch the tree arrived on, restore it as-is at the end, and never commit onto it, since gh pr merge --delete-branch would delete the outer tool's branch (work-issues/references/ship.md §9 has the restore arm).
3. Add a unit test that fails without the fix and passes with it — mandatory: a bug found by integ MUST leave a unit test behind.
4. Re-run the live repro with the fixed binary to confirm the real-AWS behavior is now correct.
5. Add a committed integ fixture under tests/integration/<name>/ exercising the fixed path end-to-end, in the SAME PR — never defer it.
6. Run /verify-pr, then open the PR.