@event4u/agent-config 1.9.1

package/.agent-src/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: systematic-debugging
+description: "Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'."
+source: package
+---
+
+# systematic-debugging
+
+## When to use
+
+* Test fails and failure is not self-explanatory
+* Bug reported (Jira, Sentry, user message), root cause not obvious
+* Production or staging shows unexpected behavior
+* Code behaves differently than the developer expected
+* A previous fix did not resolve the issue or introduced a new one
+* You catch yourself thinking "let me just try changing X"
+
+Do NOT use when:
+
+* Failure message names the fix (typo, missing import, obvious off-by-one) — fix it
+* Pure style / formatting / lint issues
+* Documentation-only questions
+
+## Goal
+
+Find the **root cause** before changing any code. A symptom fix papering
+over an unknown cause is a regression waiting to happen.
+
+## The Iron Law
+
+```
+NO FIX WITHOUT ROOT CAUSE. NO ROOT CAUSE WITHOUT EVIDENCE.
+```
+
+"I think it's probably X" is not evidence. A log line, a stack trace, a
+diff, a reproduced failure — those are evidence.
+
+## Procedure
+
+Complete each phase before the next. Skipping ahead is the single
+biggest cause of wasted debug time.
+
+### Phase 1 — Reproduce
+
+Goal: make the failure happen on demand, smallest possible setup.
+
+1. Read the error message, stack trace, and logs **in full**. Note exact
+   file, line, and the chain of calls above it.
+2. Identify the minimum input, state, or action sequence triggering the
+   failure. Intermittent → gather more data before guessing.
+3. Capture the exact reproduction as a command or a test. Prefer a
+   failing test (see [`test-driven-development`](../test-driven-development/SKILL.md))
+   — turns Phase 4 into a verified fix.
+
+Cannot reproduce? You do not yet understand the bug. Stop. Add logging,
+re-run, collect more evidence.
+
+### Phase 2 — Isolate
+
+Goal: locate the failure in a single component, layer, or call site.
+
+1. Bisect the surface area. Smallest code path that still fails? Turn
+   off/skip/mock adjacent features to narrow the window.
+2. For multi-component systems (frontend → API → service → DB, or
+   CI → build → deploy), log at **each boundary**:
+
+   * What enters the component
+   * What leaves the component
+   * What config/env the component actually sees
+
+   Goal: answer "which boundary has expected ≠ actual?".
+3. Check recent changes: `git log`, `git blame` on the failing line,
+   recent dependency updates, config edits, infra changes.
+4. **Consult memory for prior matches.** Via
+   [`memory-access`](../../guidelines/agent-infra/memory-access.md):
+   ```python
+   from scripts.memory_lookup import retrieve
+   priors = retrieve(
+       types=["incident-learnings", "historical-patterns"],
+       keys=[<error class>, <failing path(s)>],
+       limit=3,
+   )
+   ```
+   A matching `incident-learning` may already name the root cause, fix,
+   and regression test. A matching `historical-pattern` narrows the
+   hypothesis space before Phase 3. Cite matching `id`s in the evidence
+   trail.
+5. Trace backwards from the symptom. `null` arrives at line 42 — where
+   does the value originate? Walk up the call stack until the origin is
+   found. Fix at origin, not at line 42.
+
+### Phase 3 — Hypothesize
+
+Goal: one testable hypothesis at a time, rejected or confirmed by evidence.
+
+1. State the hypothesis in one sentence: *"The failure happens because
+   X, which I can confirm by observing Y."*
+2. Design the smallest possible experiment that confirms or rejects the
+   hypothesis. One variable at a time.
+3. Run it. Read the output.
+4. Confirmed → Phase 4. Rejected → back to Phase 2 with new
+   information, then form a new hypothesis.
+
+Three hypotheses in a row fail → stop. You do not understand the system
+well enough yet, or the architecture itself is the problem — see
+"Three-strike rule" below.
+
+### Phase 4 — Verify the fix
+
+Goal: the fix resolves the root cause, not just the observed symptom.
+
+1. Write or update a failing test reproducing the bug (if not already
+   done in Phase 1).
+2. Apply a single, minimal fix targeting the root cause. No bundled
+   refactors, no "while I'm here".
+3. Re-run the reproduction — failure gone.
+4. Re-run the surrounding test suite — nothing adjacent turned red.
+5. Read output carefully — no new warnings, deprecations, or silent
+   retries masking the same bug recurring.
+
+Fix does not work? **Do not** stack a second fix on top. Go back to
+Phase 2, treat the failure as new evidence.
+
+## Three-strike rule
+
+After **three** attempted fixes with the bug still present:
+
+* Stop attempting fixes.
+* Re-read phases 1–3 — something about the root cause is wrong.
+* Ask explicitly: is this bug in the code, or in the architecture /
+  design that keeps producing this class of bug?
+* Surface the question to the user. Do not attempt fix #4 silently.
+
+## Gathering evidence — cheap tools first
+
+| What you need | Tool |
+|---|---|
+| What does the code actually do at runtime? | `dd()`, `var_dump()`, `console.log()` at suspected line |
+| What does the call stack look like? | Stack trace in exception, `debug_backtrace()`, `new Error().stack` |
+| What data crosses the boundary? | Log at entry and exit of each function in the path |
+| What does an HTTP endpoint actually return? | `curl -s <url> \| jq`, Postman MCP, or `Http::fake()` assertions in tests |
+| Is the env/config what I think? | Print the actual value, do not trust the docs |
+| What changed recently? | `git log -p <file>`, `git blame -L <line>,<line> <file>` |
+| Is this a known issue? | Search tracker / Sentry / changelog of the dependency |
+| Step through execution | Xdebug — see [`php-debugging`](../php-debugging/SKILL.md) |
+
+Prefer the cheapest tool that resolves the question. A `dd()` at the
+right line beats five minutes of IDE breakpoints.
+
+## Condition-based waiting (intermittent bugs)
+
+Intermittent tests and race conditions usually stem from waiting on
+time instead of a condition. Replace `sleep(100)` or
+`setTimeout(r, 100)` with an explicit wait-for:
+
+```ts
+async function waitFor<T>(
+  check: () => T | undefined | null | false,
+  label: string,
+  timeoutMs = 5_000,
+): Promise<T> {
+  const start = Date.now();
+  while (true) {
+    const result = check();
+    if (result) return result;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`Timeout waiting for ${label} after ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+```
+
+Only use an arbitrary timeout when the timing itself is the contract
+(debounce, throttle) — add a comment explaining **why** the exact value.
+
+## Output format
+
+When reporting debug findings:
+
+1. **Symptom** — what was observed (one sentence + failure message)
+2. **Reproduction** — the command or test that triggers it
+3. **Root cause** — what is actually wrong and where
+4. **Evidence** — the log line, stack frame, or diff that proves it
+5. **Fix** — the minimal change
+6. **Regression test** — the test that catches this bug returning
+
+## Gotchas
+
+* Reading half a stack trace and jumping to a fix — the actual cause is
+  usually two or three frames above the one you read.
+* "It works on my machine" — different env than the bug report.
+  Reproduce with exact conditions from the report.
+* Adding a retry or sleep to mask an intermittent failure — hides the
+  race condition, does not fix it. Use condition-based waiting.
+* Fixing the first line that throws when the bad value came from up the
+  call chain. Trace backwards to the origin.
+* "The fix works, the test is just flaky" — flaky tests are bugs in the
+  test or the code. Diagnose them, do not retry-until-green.
+* Turning a failing assertion into a softer one ("maybe 2 or 3 retries,
+  accept both") to make it pass.
+* Bundling a bug fix with a refactor — test goes red again, cannot tell
+  which change broke it.
+
+## Red flags — STOP and restart from Phase 1
+
+* "Let me just try X and see if it works"
+* "I don't fully understand it, but this probably fixes it"
+* Proposing a fix without having reproduced the bug
+* Bundling multiple changes in one attempt
+* "It's probably a race condition, let me add a sleep"
+* A green test run after changes without having first seen it red
+* "This looks similar to bug X, so it's the same fix"
+* Suppressing a log, warning, or exception instead of tracing its source
+
+## Do NOT
+
+* Do NOT propose a fix before reproducing the bug
+* Do NOT change two things at once in a single experiment
+* Do NOT silence a warning, failing test, or noisy log as a "fix"
+* Do NOT mark a bug as fixed without a regression test
+* Do NOT attempt fix #4 after three failed fixes — surface the pattern
+
+## When to hand over to another skill
+
+* Writing the regression test → [`test-driven-development`](../test-driven-development/SKILL.md)
+* Stepping through PHP with Xdebug → [`php-debugging`](../php-debugging/SKILL.md)
+* Playwright / E2E test failures → [`playwright-testing`](../playwright-testing/SKILL.md)
+* PHPStan / Rector / ECS output → [`quality-tools`](../quality-tools/SKILL.md)
+* Verifying the fix is complete before claiming done →
+  [`verify-before-complete`](../verify-before-complete/SKILL.md)
+
+## Validation checklist
+
+Before declaring a bug fixed:
+
+* [ ] Failure was reproduced before any code changed
+* [ ] Root cause named explicitly, not "probably"
+* [ ] Evidence (log, trace, diff) supports the named root cause
+* [ ] Failing test reproducing the bug was added or updated
+* [ ] Fix is minimal, targets the root cause, not the symptom
+* [ ] Regression test now passes
+* [ ] Adjacent tests still pass
+* [ ] No warning or suppressed output hides a recurrence

package/.agent-src/skills/technical-specification/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: technical-specification
+description: "Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure."
+source: package
+---
+
+# technical-specification
+
+## When to use
+
+Use this skill when:
+- Writing a technical specification for a new feature or system
+- Creating an architecture decision record (ADR)
+- Documenting a technical RFC (Request for Comments)
+- Planning a significant technical change that needs team review
+
+Do NOT use when:
+- Trivial changes (a good PR description is enough)
+- Implementation work (use `feature-planning` or `php-coder` skill)
+
+## Procedure: Write a spec
+
+### Technical Specification (full)
+
+For complex features or systems. Stored in `agents/features/` or module `agents/features/`.
+
+```markdown
+# Technical Specification: {Title}
+
+## Status
+{ Draft | In Review | Approved | Implemented | Superseded }
+
+## Summary
+{2-3 sentences explaining what this spec proposes and why.}
+
+## Problem
+{What pain point or limitation does this address?}
+
+## Goals
+- {Specific, measurable goal}
+- {Another goal}
+
+## Non-Goals
+- {What this spec explicitly does NOT cover}
+
+## Proposed Solution
+
+### Overview
+{High-level description of the approach.}
+
+### Detailed Design
+{Technical details — data models, APIs, algorithms, flows.}
+
+### Alternatives Considered
+| Alternative | Pros | Cons | Why rejected |
+|---|---|---|---|
+
+## Migration Plan
+{How to transition from current state to the proposed solution.}
+
+## Risks and Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+
+## Open Questions
+- [ ] {Unresolved question}
+
+## References
+- {Links to related docs, tickets, or external resources}
+```
+
+### Architecture Decision Record (ADR)
+
+For significant technical decisions. Stored in `agents/decisions/`.
+
+```markdown
+# ADR-{number}: {Title}
+
+## Status
+{ Proposed | Accepted | Deprecated | Superseded by ADR-{N} }
+
+## Context
+{What is the issue? What forces are at play?}
+
+## Decision
+{What is the change that we're proposing or have agreed to implement?}
+
+## Consequences
+
+### Positive
+- {Benefit}
+
+### Negative
+- {Drawback or tradeoff}
+
+### Neutral
+- {Other notable consequences}
+```
+
+### Lightweight RFC
+
+For smaller decisions that need team input. Can be a PR description or a short doc.
+
+```markdown
+# RFC: {Title}
+
+## Proposal
+{What do you want to do?}
+
+## Why
+{Why is this needed?}
+
+## How
+{Brief technical approach.}
+
+## Impact
+{What does this change? Who is affected?}
+
+## Open for feedback until: {date}
+```
+
+## Writing guidelines
+
+### Be specific, not vague
+
+```
+❌ "The system should be fast"
+✅ "API response time should be < 200ms at p95 for list endpoints"
+```
+
+### Include constraints
+
+- Performance requirements (latency, throughput)
+- Compatibility requirements (PHP version, browser support)
+- Security requirements (authentication, data sensitivity)
+- Scale requirements (data volume, concurrent users)
+
+### Show your reasoning
+
+Don't just present the solution — show **why** it was chosen over alternatives.
+The "Alternatives Considered" section is often the most valuable part.
+
+### Keep it actionable
+
+A spec should be implementable by someone who wasn't in the original discussion.
+If a developer reads only this document, they should be able to build it.
+
+## Integration with other systems
+
+- **Feature plans** reference specs when technical depth is needed.
+- **Roadmaps** are generated from specs after approval.
+- **ADRs** are referenced from `AGENTS.md` or module docs for historical context.
+- **Sessions** link to the spec being implemented.
+
+## Output format
+
+1. Technical specification document with architecture decisions
+2. API contracts, data models, and sequence diagrams
+3. Implementation plan with dependencies
+
+## Auto-trigger keywords
+
+- technical spec
+- RFC
+- ADR
+- architecture decision
+
+### Validate
+
+- Verify every section of the spec template is filled in (no placeholders left).
+- Confirm constraints and limitations are explicit, not implied.
+- Check that the spec answers: What, Why, How, What not, and When.
+
+## Gotcha
+
+- A spec without constraints is fiction — always include technical limitations, timeline, and scope boundaries.
+- The model tends to write specs that describe the ideal solution without acknowledging existing code.
+- Don't write specs for trivial features — a spec is overhead that's only worth it for complex changes.
+
+## Do NOT
+
+- Do NOT write specs without researching the codebase first.
+- Do NOT present only one option — always consider alternatives.
+- Do NOT leave specs in "Draft" forever — push for a decision.
+- Do NOT implement before the spec is reviewed (for significant changes).

package/.agent-src/skills/terraform/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: terraform
+description: "Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform."
+source: package
+---
+
+# terraform
+
+## When to use
+
+Use this skill when writing or modifying Terraform configurations (`.tf` files), creating new infrastructure modules, or understanding AWS resource definitions.
+
+## Procedure: Write Terraform config
+
+1. Read the infrastructure repo structure (check `agents/overrides/skills/terraform.md` for the repo location).
+2. Check existing modules in `modules/` for patterns and conventions.
+3. Read `variables.tf` of the target module to understand required inputs.
+4. Check `versions.tf` for provider version constraints.
+
+## Project structure (typical)
+
+```
+{infrastructure-repo}/
+├── environments/
+│   ├── pro/                    # Production environment
+│   │   ├── root.hcl            # Terragrunt root config
+│   │   ├── core/               # Core infrastructure (VPC, DNS zones)
+│   │   └── {service}/          # Per-service resources
+│   └── sta/                    # Stage environment
+│       └── ...
+├── modules/
+│   ├── core/                   # VPC, DNS, shared resources
+│   └── {service}/              # Per-service module (ECS, ALB, ECR, etc.)
+└── Taskfile.yml                # Task runner commands (or Makefile)
+```
+
+Read `agents/overrides/skills/terraform.md` for the actual repository layout and service names.
+
+## Conventions
+
+### Provider versions
+
+- Always pin provider versions in `versions.tf`.
+- Check `versions.tf` in the existing modules for the project's version constraints.
+
+### Module sources
+
+Prefer community or organization-specific Terraform modules from the Terraform Registry:
+
+```hcl
+module "alb" {
+  source  = "{org}/application-load-balancer/aws"
+  version = ">= 1.0.0, < 2.0.0"
+}
+```
+
+Check existing modules in the project for which registry modules are used.
+
+### Naming
+
+- Resource prefix: `var.global_prefix` (e.g., `{project}-{env}`)
+- All resources must include `tags = var.tags`
+- Security groups: `${var.global_prefix}-<purpose>` (e.g., `-ecs`, `-mysql`, `-redis`)
+- Log groups: `/aws/ecs/${cluster}/${service}`
+
+### State management
+
+- Remote state in **S3** with **DynamoDB** locking.
+- State is encrypted.
+- Key pattern: `${path_relative_to_include()}/terraform.tfstate`
+
+### Variables
+
+- Use typed `variable` blocks with `description`.
+- Use `object()` types for complex inputs (not `any` unless unavoidable).
+- Use `optional()` with defaults where appropriate.
+- Group variables by domain (naming, network, ECS, Redis, database, etc.).
+
+### Lifecycle rules
+
+- Use `ignore_changes = [task_definition]` on ECS services — task definitions are managed by CI/CD, not Terraform.
+- Use `deletion_protection = true` on databases.
+
+### Security
+
+- OIDC authentication for GitHub Actions (no long-lived credentials).
+- Secrets stored in **AWS Secrets Manager**.
+- Security groups follow least-privilege: only allow traffic between known services.
+- IAM policies use specific resource ARNs, not wildcards (except where unavoidable).
+
+## Common patterns
+
+### ECS service with CodeDeploy (Blue/Green)
+
+Used for web services with zero-downtime deployments:
+- ALB → Target Group → ECS Service
+- CodeDeploy handles traffic shifting
+- Auto-rollback on CloudWatch alarms (5xx error rate)
+
+### ECS service without CodeDeploy
+
+Used for workers and schedulers:
+- Direct ECS service update
+- `deployment_controller { type = "ECS" }`
+- `lifecycle { ignore_changes = [task_definition] }`
+
+### GitHub OIDC IAM role
+
+Each environment has a GitHub IAM role with:
+- OIDC trust policy (scoped to repo + environment)
+- Policies for ECR push/pull, ECS deployment, Secrets Manager read, CloudWatch logs
+
+## Output format
+
+1. Terraform configuration files (.tf) with proper module structure
+2. Variables, outputs, and state management config
+
+## Auto-trigger keywords
+
+- Terraform
+- AWS infrastructure
+- modules
+- resources
+- state management
+
+## Gotcha
+
+- `terraform apply` without `-auto-approve` requires interactive confirmation — don't use in CI without the flag.
+- The model forgets to run `terraform plan` before `apply` — always plan first, review changes.
+- State files contain sensitive data — never commit them to Git. Use remote state (S3 + DynamoDB).
+
+## Do NOT
+
+- Do NOT use `*` in IAM resource ARNs unless absolutely necessary.
+- Do NOT remove `deletion_protection` from databases.
+- Do NOT change provider versions without testing in Stage first.
+- Do NOT hardcode AWS account IDs — use `data.aws_caller_identity.current`.