@groupby/ai-dev 0.5.10 → 0.5.11

package/teams/fhr-neowise/skills/pull-request-authoring/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pull-request-authoring
+description: "Apply when opening or updating a GitHub pull request for a branch — classifying the change as complex / simple / non-code, titling it FHR-XXXX: <Ticket Title>, rendering the matching template, drawing Mermaid diagrams for complex changes, and creating or updating the PR via gh."
+user-invocable: false
+---
+
+# Skill: Pull Request Authoring
+
+## When This Applies
+
+Apply this skill whenever creating or updating a GitHub pull request for the current branch — whether triggered by `/write-pr` or when the user asks to "open a PR", "write a PR description", or "update the PR".
+
+## Title Format — Non-Negotiable
+
+Every PR title is exactly:
+
+```
+FHR-<number>: <Ticket Title>
+```
+
+- `FHR-<number>` comes from the branch name (e.g. `FHR-7162-refine-our-current-harness` → `FHR-7162`).
+- `<Ticket Title>` is the **exact Jira ticket summary** — fetch it, do not paraphrase or invent one.
+  - Use the Atlassian MCP tools (`getJiraIssue`) to read the ticket summary for the key.
+  - If Jira is unavailable, derive a candidate title from the branch slug, render it, and **ask the user to confirm or correct it** before publishing.
+- The ticket number in the title must match the branch's ticket number.
+
+## Step 1 — Gather the change
+
+- Confirm the base branch (`master` unless told otherwise) and the head branch (current).
+- List the changed files and stats vs base:
+  - `git diff --stat master...HEAD`
+  - `git diff --name-status master...HEAD`
+- Extract the ticket key from the branch name (pattern `[A-Z]+-\d+`).
+- Check whether a PR already exists for the branch: `gh pr list --head <branch> --json number,url,title`.
+
+## Step 2 — Classify the PR type
+
+Inspect the changed files and decide the type. **When in doubt, escalate to the more thorough type.**
+
+| Type | Signals | Template |
+|------|---------|----------|
+| **Non-code** | Only docs/config (`.md`, `.json`, `.yml`, `.toml`, `.txt`, CI config), no `src/` changes, no test changes | `NON-CODE.template.md` |
+| **Simple code** | Source changed in a single module; localized (a handful of files); no changed control/data flow, no new public types/contracts, no cross-service impact | `SIMPLE.template.md` |
+| **Complex code** | Any one of: multiple modules; new/removed classes or public types; changed control or data flow; new/changed API, GraphQL, or SQL contract; schema/migration change; cross-service interaction | `COMPLEX.template.md` |
+
+State the chosen type and the one-line reason, and **confirm with the user** before rendering (the user may override). A type override passed to `/write-pr` (e.g. `type=complex`) skips detection.
+
+## Step 3 — Resolve the title
+
+Build `FHR-<number>: <Ticket Title>` per the rules above. Fetch the Jira summary; only fall back to a branch-derived title (with user confirmation) when Jira is unavailable.
+
+## Step 4 — Render the template
+
+Read the matching template file from this skill folder and fill every placeholder from the diff. Delete any optional section that genuinely does not apply rather than leaving it empty. Keep the depth proportional to the type — do not pad a simple PR or thin out a complex one.
+
+## Step 5 — Diagrams (complex PRs only)
+
+A complex PR **must include at least one Mermaid diagram**. Choose the diagram type(s) that best explain *this* change — never add a diagram that adds no insight:
+
+| When the change... | Use |
+|--------------------|-----|
+| alters control or data flow | `flowchart` (show before → after) |
+| adds/changes classes, types, or their relationships | `classDiagram` |
+| changes how services/components interact at runtime | `sequenceDiagram` |
+| changes a state machine | `stateDiagram` |
+| changes a schema or entity model | `erDiagram` |
+
+Invoke the **`mermaid-diagram`** skill (in `.claude/skills/mermaid-diagram/`) to produce correct, renderable syntax. Embed each diagram as a ```mermaid fenced block in the body — GitHub renders these natively. Prefer a before/after pair (or annotate what changed) so reviewers see the *delta*, not just the end state.
+
+## Step 6 — Review and approve
+
+Present the full rendered title and body to the user. Do **not** create, update, or push anything yet. Support correction cycles: if the user requests changes, re-render and present again. Continue only once the user explicitly approves.
+
+## Step 7 — Save and publish
+
+1. Save the approved body to `PR.md` next to the ticket's spec/plan: locate `.sprints/*/<ticket>/`. If exactly one exists, write `PR.md` there; if none or several exist, ask the user where to save it.
+2. Ensure the branch is pushed: `git push -u origin <branch>` — pushing requires user confirmation.
+3. Create or update the PR using the saved file:
+   - New PR: `gh pr create --base master --head <branch> --draft --title "FHR-<number>: <Ticket Title>" --body-file <path>/PR.md`
+   - Existing PR: `gh pr edit <number> --title "FHR-<number>: <Ticket Title>" --body-file <path>/PR.md`
+4. Report the PR URL.
+
+Creating, updating, and pushing are outward-facing — only do them after the explicit approval in Step 6.
+
+## Templates
+
+| File | PR type |
+|------|---------|
+| `COMPLEX.template.md` | Complex code change — full template with Mermaid diagrams |
+| `SIMPLE.template.md` | Simple code change — description + impacted areas |
+| `NON-CODE.template.md` | Non-code change — bullet-point summary |
+
+## Red Flags — STOP and Re-Evaluate
+
+| Thought | Reality |
+|---------|---------|
+| "I'll write a clear title that describes the change" | The title is the **exact Jira ticket summary**, format `FHR-<number>: <Ticket Title>`. Fetch it; don't paraphrase. |
+| "This complex change reads fine as prose" | Complex PRs require at least one Mermaid diagram. Use the `mermaid-diagram` skill. |
+| "Diagrams are effort — I'll call it a simple PR" | Classify by the change, not the effort. Multi-module / new types / changed flow = complex. When in doubt, complex. |
+| "A small fix doesn't need impacted areas" | Simple PRs must list the places touched — that is the reviewer's map. |
+| "The description looks good, I'll just open the PR" | Show title + body and get explicit approval first. Creating and pushing are outward-facing. |
+| "I'll write the body inline on the gh command" | Save `PR.md` and use `--body-file` — it avoids shell-escaping and leaves a traceable artifact. |

package/teams/fhr-neowise/skills/spec-investigation/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: spec-investigation
+description: "Apply when researching and writing a SPEC.md: investigating a ticket, exploring the codebase, identifying unknowns, and structuring a complete specification that an AI coding agent can execute without further clarification."
+user-invocable: false
+---
+
+# Skill: Spec Investigation
+
+## When This Applies
+
+Use this skill whenever producing a SPEC.md — whether triggered by `/write-spec` or when Claude determines that spec research is needed before planning or implementing a feature.
+
+## Template
+
+The spec template is at `TEMPLATE.spec.md` in this skill folder. Read it before writing any spec.
+
+## Investigation Process
+
+Work through all steps in order. Do not skip steps.
+
+### Step 0 — Scope decomposition check
+
+Before anything else, assess whether the input describes multiple independent subsystems or features that would make better separate specs.
+
+Signs that decomposition is needed:
+- The request touches more than two unrelated modules with no shared contract
+- There are multiple distinct user-facing outcomes that could ship independently
+- A junior engineer reading the ticket would have trouble deciding where to start
+
+If decomposition is warranted: present the proposed sub-specs, explain the split, and ask the developer to confirm which sub-feature to tackle first. Each sub-feature gets its own full investigation and SPEC.md. Do not proceed until the scope of *this* spec is agreed.
+
+If the scope is appropriate for a single spec, proceed directly to Step 1.
+
+### Step 1 — Gather ticket and requirement context
+
+If a Jira ticket key is provided (pattern: `[A-Z]+-\d+`, e.g. `FHR-7106`):
+- Use available Atlassian MCP tools to fetch the ticket: title, description, acceptance criteria, comments, linked Confluence pages, sprint metadata.
+- If Atlassian MCP is unavailable, ask the user to paste the ticket description.
+- Extract the sprint name and ticket number for the output path and spec header.
+
+If no ticket key is provided, use the feature description as primary input. Ask the user for the sprint name and ticket number before creating any directory.
+
+**Ticket clarity check**: After gathering context, assess whether the requirements are concrete and unambiguous. A well-defined ticket has clear acceptance criteria, a bounded scope, and only one reasonable interpretation. A vague ticket has phrases like "improve X", "support Y somehow", or no acceptance criteria at all.
+
+If the ticket is vague, enter collaborative dialogue mode before continuing:
+- Ask clarifying questions **one at a time** — never bundle multiple questions in one message
+- Prefer multiple-choice questions when the answer space is bounded
+- Focus on: purpose (why is this needed now?), constraints (what must not break or change?), success criteria (how will the developer know it's done?)
+- Continue until you have enough to write concrete given/when/then requirements
+
+If the ticket is already well-defined, proceed without asking unnecessary questions.
+
+### Step 2 — Understand the codebase
+
+Search the workspace for everything relevant to the feature:
+- Existing components, services, classes, or functions the feature touches
+- Existing tests that describe current behavior in the affected area
+- Existing data models, schemas, or API contracts in scope
+- Utilities or abstractions that should be reused
+
+Use `grep` (via Bash), `find`, and Read to explore. Parallelize independent reads.
+
+For each relevant file, record its path and classification: read-only context, needs modification, or will be created.
+
+### Step 3 — Check prior work on GitHub
+
+Search for related pull requests and issues using available GitHub MCP tools (`search_pull_requests`, `issue_read`, `pull_request_read`). Look for previous attempts at the same or similar work and open issues adding context or constraints. Record any findings that constrain or inform the spec.
+
+### Step 4 — Identify unknowns
+
+List everything still unclear after Steps 1–3:
+- Missing API or data contracts
+- Ambiguous behavior (errors, empty input, concurrent access)
+- Architecture decisions with more than one valid option
+- Security or performance requirements not mentioned in the input
+
+### Step 5 — Propose implementation approaches
+
+Based on your findings from Steps 2–4, propose **2–3 distinct implementation approaches**. For each:
+- Describe the approach in 2–3 sentences
+- List trade-offs: complexity, testability, performance, risk, amount of existing code reused
+- State your recommended approach and the reason
+
+Ask the developer to pick an approach before continuing. The chosen approach anchors the spec's architecture and technical constraints sections.
+
+If there is genuinely only one reasonable approach, describe it briefly and confirm with the developer rather than fabricating alternatives. Do not proceed to Step 6 until the approach is agreed.
+
+### Step 6 — Research online if needed
+
+If the chosen approach involves an external library or pattern that needs verification, use WebFetch or WebSearch. Only fetch pages directly relevant to a confirmed unknown — do not research speculatively.
+
+### Step 7 — Ask the developer
+
+If open questions remain after Steps 1–6, ask all of them in a single message before writing. Group by category: Behavior, Scope, Architecture, Data. Wait for answers before proceeding.
+
+### Step 8 — Present a findings summary and confirm
+
+Before writing the spec, present a concise pre-write summary:
+- **Affected files**: what will be modified and what will be created
+- **Chosen approach**: one sentence recapping the approach from Step 5
+- **Key assumptions**: the most consequential assumptions being written into the spec
+- **Remaining risks**: anything still uncertain that could require revisiting the spec later
+
+Ask: "Does this look right before I write the spec?" Wait for the developer's response. If they request changes, revisit the relevant steps before proceeding.
+
+### Step 9 — Write the spec
+
+- Create the directory `.sprints/<sprint-name>/<ticket-number>/` if it does not exist.
+- Write the spec to `.sprints/<sprint-name>/<ticket-number>/SPEC.md` using the template structure.
+- Be concrete: exact file paths, method names, field names, types. No vague descriptions.
+- Out of Scope: list at least one item explicitly, even if it is "no changes to other modules".
+- Context: every file path from Steps 2–3, classified as read-only, modify, or create.
+- Functional Requirements: given/when/then format, at least one edge case per requirement.
+- Assumptions & Open Questions: every assumption made in Steps 1–8 must appear here.
+- Acceptance Criteria: every requirement must have at least one corresponding criterion.
+
+### Step 10 — Self-review the spec
+
+After writing, look at the spec with fresh eyes. Fix any issues inline — do not present the spec until this review passes.
+
+1. **Placeholder scan**: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them before presenting.
+2. **Internal consistency**: Does the chosen architecture from Step 5 match what is written in Technical Constraints and Functional Requirements? If sections contradict each other, resolve it.
+3. **Scope check**: Is this focused enough for a single implementation plan? If it has grown to cover multiple independent concerns, flag it for decomposition.
+4. **Ambiguity check**: Can any requirement be interpreted two ways? If so, pick one and state it explicitly.
+5. **Validation checklist**:
+   - [ ] Spec saved at `.sprints/<sprint-name>/<ticket-number>/SPEC.md`
+   - [ ] Goal and measurable success criteria are concrete — not placeholder text
+   - [ ] Out of Scope is filled in
+   - [ ] Context has specific file paths
+   - [ ] At least one given/when/then requirement exists
+   - [ ] No unresolved open questions
+   - [ ] At least one checkable acceptance criterion
+   - [ ] Agent and module are identified in the spec header
+
+Fix any failing items before presenting.
+
+## Output Summary
+
+Present: what the spec covers, the chosen implementation approach and why, codebase findings that influenced it, assumptions the developer should confirm before implementation starts.

package/teams/fhr-neowise/skills/spec-investigation/TEMPLATE.spec.md

@@ -0,0 +1,74 @@
+# Spec: [Feature Title]
+
+Date: YYYY-MM-DD
+
+> **Agent**: <!-- Which agent should handle this? e.g. Angular Dev, Java Dev, Scala Dev -->
+> **Module**: <!-- Which module(s) are in scope? e.g. insights-dashboard, reporting-api-v2 -->
+> **Ticket**: <!-- Link to the Jira/GitHub issue -->
+
+---
+
+## 1. Objective
+
+- **Goal**: One or two sentences describing what this feature achieves and why it is needed.
+- **Success Criteria**: What observable state proves this is complete? Be specific and measurable.
+
+## 2. Out of Scope
+
+Explicitly list what this spec does NOT cover. This prevents scope creep and stops the agent from over-engineering.
+
+- ...
+
+## 3. Context
+
+**Files to read for context** (understand but do not modify):
+- `path/to/relevant/file.ts`: reason why it is relevant
+
+**Files to modify**:
+- `path/to/existing/file.ts`: what changes are needed
+
+**Files to create**:
+- `path/to/new/file.ts`: purpose
+
+## 4. Functional Requirements
+
+Describe each requirement as a concrete behavior: given an input or trigger, what must happen?
+
+1. **[Requirement name]**: Given [input/state], when [action], then [expected outcome].
+2. **[Requirement name]**: Include edge cases (empty input, error state, boundary values).
+3. **[Requirement name]**: Include any API or UI contract changes with exact field names and types.
+
+## 5. Technical Constraints
+
+- **Architecture**: Which pattern must be followed (e.g., the service handles logic, the component is presentation-only).
+- **Security**: Any authentication, authorization, input validation, or data sensitivity requirements.
+- **Performance**: Any latency, throughput, or bundle-size requirements.
+- **Dependencies**: Any specific library versions or APIs to use or avoid. Flag if a new dependency is needed.
+
+## 6. Assumptions & Open Questions
+
+List anything assumed to be true but not yet confirmed, and anything needing a decision before work can start.
+
+**Assumptions**:
+- ...
+
+**Open Questions**:
+- ...
+
+## 7. Acceptance Criteria
+
+Each criterion describes an observable behavior that can be verified. Written as: "Given [context], when [action], then [outcome]."
+
+- [ ] Given ..., when ..., then ...
+- [ ] Given ..., when ..., then ...
+- [ ] All existing tests continue to pass with no regressions.
+- [ ] No new dependencies introduced without explicit approval in this spec.
+
+## 8. Definition of Done
+
+- [ ] All acceptance criteria above are met.
+- [ ] Unit tests cover every acceptance criterion and every branch.
+- [ ] Tests are green locally.
+- [ ] No lint or type errors.
+- [ ] No TODO, FIXME, or placeholder code.
+- [ ] No secrets, hardcoded URLs, or environment-specific values in source.

package/teams/fhr-neowise/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: tdd-workflow
+description: "Apply when implementing any feature or bugfix — before writing any production code. Also use when confirming RED vs GREEN test state, looking up test commands by module, or deciding when to commit."
+user-invocable: false
+---
+
+# Skill: TDD Workflow
+
+**REQUIRED BACKGROUND:** You MUST understand `superpowers:test-driven-development` — it defines the fundamental discipline this skill applies to this project.
+
+## When This Applies
+
+Apply this skill during any TDD implementation — whether orchestrated by `/tdd-implementation` or when Claude is writing code and tests in any module of this project.
+
+## Double-Loop TDD
+
+```
+Outer Loop (Integration / Acceptance)          Inner Loop (Unit)
+┌─────────────────────────────────┐            ┌──────────────────────┐
+│ 1. Write a failing integration  │            │ 1. Write a failing   │
+│    test (RED)                   │            │    unit test (RED)   │
+│                                 │            │                      │
+│ 2. Enter inner loop ───────────────────────► │ 2. Write minimal     │
+│                                 │            │    code (GREEN)      │
+│                                 │            │                      │
+│                                 │  ◄──────── │ 3. Refactor (CLEAN)  │
+│                                 │  repeat    │                      │
+│ 3. Integration test passes      │  until     └──────────────────────┘
+│    (GREEN)                      │  green
+│                                 │
+│ 4. Refactor across units        │
+│    (CLEAN)                      │
+└─────────────────────────────────┘
+```
+
+**Rules:**
+- Never write production code without a failing test.
+- Each RED-GREEN-REFACTOR cycle should take minutes, not hours.
+- Run the relevant test suite after every GREEN step to confirm no regressions.
+- Commit at every GREEN boundary (all tests pass).
+
+## Confirming Red vs Green
+
+After a tester agent writes tests: at least one test must **FAIL**. A run with zero failures means the tester did not write a genuinely failing test — re-invoke the tester with the passing output and ask for a more specific failing assertion.
+
+After a dev agent implements code: **zero failures**, and the count of passing tests must have increased by at least the number of tests the tester wrote.
+
+## Test Commands by Language
+
+### Java — Unit Tests
+
+```bash
+./gradlew :<module>:test
+./gradlew :<module>:test --tests "com.fredhopper.reporting.<ClassName>Test"
+```
+
+### Java — Integration Tests
+
+```bash
+./gradlew :<module>:integrationTest
+./gradlew :<module>:integrationTest --tests "*TestRunner*"
+```
+
+Integration tests live in `src/integration/` and require Docker (Testcontainers).
+
+### Scala — Unit Tests
+
+```bash
+./gradlew :<module>:test
+./gradlew :<module>:test --tests "*MySpec*"
+```
+
+### Scala — Integration Tests
+
+```bash
+./gradlew :<module>:integrationTest
+```
+
+### Angular — Spec Tests
+
+```bash
+# insights-dashboard
+cd insights-dashboard && npm test
+cd insights-dashboard && npm test -- --testPathPattern="feature-name.component.spec"
+
+# insights-admin-console
+cd insights-admin-console && npm test
+cd insights-admin-console && npm test -- --testPathPattern="feature-name.component.spec"
+```
+
+### Python — Unit Tests
+
+```bash
+cd statistical-analysis && PYTHONPATH=main pytest test/ -v
+cd statistical-analysis && PYTHONPATH=main pytest test/test_<module>.py -v
+./gradlew :statistical-analysis:test
+```
+
+### Python — Integration Tests
+
+```bash
+cd statistical-analysis && pytest test_integration/ -v
+cd statistical-analysis && pytest test_integration/test_integration_<feature>.py -v
+```
+
+## Commit at GREEN Boundary
+
+When all tests pass after a completed step:
+
+1. Stage only the files changed in this step (avoid unrelated changes).
+2. Run `./gradlew spotlessApply` for any Java or Groovy changes.
+3. Commit with format: `<TICKET>: <imperative description of what this step does>`
+4. Ask the user whether to push: only `git push` if explicitly confirmed.
+
+If a pre-commit hook fails: fix the underlying issue and create a **new** commit. Never use `--no-verify`.
+
+## Handling Persistent Failures
+
+When tests still fail after implementing:
+- Attempt 1: re-invoke the dev agent with the full failure output.
+- Attempt 2: re-invoke the dev agent once more.
+- After 2 failed attempts: stop, report the full failing test output, and wait for the user to provide guidance before continuing.
+
+## Red Flags — STOP and Re-Evaluate
+
+These thoughts mean you are rationalizing. Stop and follow the rules:
+
+| Thought | Rule |
+|---------|------|
+| "It's too simple to need a test" | Write the test. Simple code breaks too. |
+| "The acceptance test will cover it" | Unit test cost: ~90 seconds. Write it. |
+| "We're under time pressure" | Skipping tests creates the next sprint's time pressure. |
+| "I'll test it after the feature is wired up" | Tests-after verify what code does. Tests-first define what it should do. |
+| "The test would just mirror the implementation" | That IS a valid unit test. Write it. |
+| "I already manually tested it" | Manual tests don't run in CI. Write the automated test. |
+
+**All of these mean: write the failing test first. No exceptions.**