ecoportal-api-graphql 1.3.14 → 1.3.15

data/.ai-assistance/skills/gemini-assist/SKILL.md

@@ -1,63 +1,63 @@
-# SKILL: Gemini Assist
-
-**Purpose:** Offload large-context tasks to Gemini to save Claude token quota, speed up development, and leverage Gemini's wide context window.
-
----
-
-## When to Use
-
-- The task requires reading many files at once (e.g. whole-gem analysis, cross-cutting refactor planning).
-- A task is mostly "read and summarise / read and advise" rather than "write code" — Gemini handles these cheaply.
-- You're doing a cycle-end review and want a second pass over a large diff or many changed files.
-- Token budget is running low and the task doesn't require Claude's nuanced judgement for the current step.
-
-## When NOT to Use
-
-- Tasks that require writing or editing actual code (Claude applies changes; Gemini only advises).
-- Tasks where hallucination risk is high and verification would cost more time than doing it directly.
-- Short tasks that fit comfortably in Claude's context — the overhead isn't worth it.
-
----
-
-## How to Invoke
-
-Run from the repo root:
-
-```bash
-ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-  --prompt "Your question or instruction here" \
-  --files path/to/file1.rb path/to/file2.rb \
-  [--model gemini-1.5-pro]
-```
-
-Or pass a prompt file:
-
-```bash
-ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-  --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
-  --files "lib/ecoportal/api/graphql/**/*.rb"
-```
-
-**Environment variable required:** `GEMINI_API_KEY` — set in `.env` at repo root (git-ignored).
-**Optional:** `GEMINI_MODEL` — defaults to `gemini-1.5-pro`. Override in `.env` or via `--model`.
-
----
-
-## Output Handling (IMPORTANT)
-
-Gemini responses **must always be reviewed** before acting on them:
-
-1. Read the response carefully.
-2. Cross-check any specific claims (method names, class hierarchies, argument counts) against the actual code.
-3. Where Gemini proposes code changes, treat them as a draft — apply only after verifying correctness.
-4. Where Gemini flags issues in a cycle-end review, confirm each issue is real before proposing a fix to the developer.
-
----
-
-## Prompting Tips for Best Results
-
-- Give Gemini explicit instructions: what to look for, what to ignore, what format to respond in.
-- Tell it the role: "You are reviewing a Ruby gem. Focus on X. Do not suggest Y."
-- Ask for a structured output (e.g. "Respond with a numbered list of concerns, each with: file, line range, issue, suggested fix").
-- For large reviews, ask it to triage by severity first.
-- Use the pre-built prompt in `prompts/cycle_end_review.txt` for end-of-cycle reviews.
+# SKILL: Gemini Assist
+
+**Purpose:** Offload large-context tasks to Gemini to save Claude token quota, speed up development, and leverage Gemini's wide context window.
+
+---
+
+## When to Use
+
+- The task requires reading many files at once (e.g. whole-gem analysis, cross-cutting refactor planning).
+- A task is mostly "read and summarise / read and advise" rather than "write code" — Gemini handles these cheaply.
+- You're doing a cycle-end review and want a second pass over a large diff or many changed files.
+- Token budget is running low and the task doesn't require Claude's nuanced judgement for the current step.
+
+## When NOT to Use
+
+- Tasks that require writing or editing actual code (Claude applies changes; Gemini only advises).
+- Tasks where hallucination risk is high and verification would cost more time than doing it directly.
+- Short tasks that fit comfortably in Claude's context — the overhead isn't worth it.
+
+---
+
+## How to Invoke
+
+Run from the repo root:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt "Your question or instruction here" \
+  --files path/to/file1.rb path/to/file2.rb \
+  [--model gemini-1.5-pro]
+```
+
+Or pass a prompt file:
+
+```bash
+ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+  --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+  --files "lib/ecoportal/api/graphql/**/*.rb"
+```
+
+**Environment variable required:** `GEMINI_API_KEY` — set in `.env` at repo root (git-ignored).
+**Optional:** `GEMINI_MODEL` — defaults to `gemini-1.5-pro`. Override in `.env` or via `--model`.
+
+---
+
+## Output Handling (IMPORTANT)
+
+Gemini responses **must always be reviewed** before acting on them:
+
+1. Read the response carefully.
+2. Cross-check any specific claims (method names, class hierarchies, argument counts) against the actual code.
+3. Where Gemini proposes code changes, treat them as a draft — apply only after verifying correctness.
+4. Where Gemini flags issues in a cycle-end review, confirm each issue is real before proposing a fix to the developer.
+
+---
+
+## Prompting Tips for Best Results
+
+- Give Gemini explicit instructions: what to look for, what to ignore, what format to respond in.
+- Tell it the role: "You are reviewing a Ruby gem. Focus on X. Do not suggest Y."
+- Ask for a structured output (e.g. "Respond with a numbered list of concerns, each with: file, line range, issue, suggested fix").
+- For large reviews, ask it to triage by severity first.
+- Use the pre-built prompt in `prompts/cycle_end_review.txt` for end-of-cycle reviews.

data/.ai-assistance/skills/project-cycle/SKILL.md

@@ -1,177 +1,177 @@
-# SKILL: Project Preparation, Maintenance & Cycle
-
-**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
-
----
-
-## When to Use
-
-- A developer describes a new piece of work.
-- Picking up an existing project after a gap.
-- A cycle of changes is complete and needs a closing review.
-
----
-
-## Folder Structure
-
-```
-.ai-assistance/projects/<project-slug>/
-  INTENT.md          What we're trying to achieve and why
-  TODO.md            Ordered task list, ticked off as done
-  DECISIONS.md       Key decisions made and why
-  UPSTREAM.md        Upstream dependency changes needed (if any)
-```
-
-Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
-
----
-
-## Starting a Project
-
-1. Ask the developer: "What are we trying to change and why?"
-2. Capture the answer in `INTENT.md` (see template below).
-3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
-4. Break the intent into an ordered TODO list in `TODO.md`.
-5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
-
-### INTENT.md template
-
-```markdown
-# Project: <Name>
-
-**Created:** YYYY-MM-DD
-**Status:** [active | paused | complete]
-**Branch:** feature/<slug>
-**Target branch:** main
-
-## Goal
-One paragraph: what we want to achieve.
-
-## Motivation
-Why now? What problem does this solve?
-
-## Scope
-What's in scope. What's explicitly out of scope.
-
-## Success Criteria
-How we'll know it's done.
-```
-
----
-
-## TODO.md format
-
-```markdown
-# TODOs — <Project Name>
-
-- [ ] Task description  <!-- add detail as needed -->
-- [x] Completed task
-```
-
-Tick items off as they're completed. Never delete items — the history matters.
-
----
-
-## DECISIONS.md format
-
-```markdown
-# Decisions — <Project Name>
-
-## [DATE] <Decision title>
-
-**Context:** What made this decision necessary.
-**Options considered:** Brief list.
-**Decision:** What was chosen.
-**Reason:** Why.
-**Consequences:** What this means going forward.
-```
-
----
-
-## Session Start — Git Orientation (Always Do This)
-
-Before any other work, run:
-
-```bash
-# 1. Confirm current branch
-git branch --show-current
-
-# 2. Check how far ahead of target branch
-git rev-list --count main..HEAD
-
-# 3. Get a cheap summary of what's changed
-git diff main...HEAD --stat
-```
-
-Cross-reference the diff stat against the active project's `TODO.md`:
-- Changed files should map to ticked TODO items.
-- Unticked TODOs with no corresponding changed files = work not yet started.
-- Changed files with no corresponding TODO = untracked work, worth noting.
-
-If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
-
-If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
-
----
-
-## Cycle-End Review
-
-When all TODOs are ticked:
-
-1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
-2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
-   ```bash
-   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
-     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
-     --output .ai-assistance/projects/<slug>/gemini_review.txt \
-     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
-   ```
-3. Review Gemini's output — verify each claim against actual code before acting.
-4. Propose fixes for genuine issues — confirm with developer.
-5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
-6. Update `INTENT.md` status to `complete`.
-7. Prompt: "Ready to open the MR / start the next project?"
-
----
-
-## Upstream Dependency Changes
-
-If changes require modifying an upstream gem:
-
-Options (present all three to developer):
-
-1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
-2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
-3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
-
-Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
-
----
-
-## Session / Collaborator Setup (First Time on a Machine)
-
-When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
-
-1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
-
-2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
-
-   | Gem | Remote |
-   |-----|--------|
-   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
-   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
-   | `graphlient` | https://github.com/rellampec/graphlient.git |
-   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
-   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
-
-3. For each one they have locally:
-   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
-   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
-
-4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
-
-5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
-
-6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
-
-If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"
+# SKILL: Project Preparation, Maintenance & Cycle
+
+**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
+
+---
+
+## When to Use
+
+- A developer describes a new piece of work.
+- Picking up an existing project after a gap.
+- A cycle of changes is complete and needs a closing review.
+
+---
+
+## Folder Structure
+
+```
+.ai-assistance/projects/<project-slug>/
+  INTENT.md          What we're trying to achieve and why
+  TODO.md            Ordered task list, ticked off as done
+  DECISIONS.md       Key decisions made and why
+  UPSTREAM.md        Upstream dependency changes needed (if any)
+```
+
+Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
+
+---
+
+## Starting a Project
+
+1. Ask the developer: "What are we trying to change and why?"
+2. Capture the answer in `INTENT.md` (see template below).
+3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
+4. Break the intent into an ordered TODO list in `TODO.md`.
+5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
+
+### INTENT.md template
+
+```markdown
+# Project: <Name>
+
+**Created:** YYYY-MM-DD
+**Status:** [active | paused | complete]
+**Branch:** feature/<slug>
+**Target branch:** main
+
+## Goal
+One paragraph: what we want to achieve.
+
+## Motivation
+Why now? What problem does this solve?
+
+## Scope
+What's in scope. What's explicitly out of scope.
+
+## Success Criteria
+How we'll know it's done.
+```
+
+---
+
+## TODO.md format
+
+```markdown
+# TODOs — <Project Name>
+
+- [ ] Task description  <!-- add detail as needed -->
+- [x] Completed task
+```
+
+Tick items off as they're completed. Never delete items — the history matters.
+
+---
+
+## DECISIONS.md format
+
+```markdown
+# Decisions — <Project Name>
+
+## [DATE] <Decision title>
+
+**Context:** What made this decision necessary.
+**Options considered:** Brief list.
+**Decision:** What was chosen.
+**Reason:** Why.
+**Consequences:** What this means going forward.
+```
+
+---
+
+## Session Start — Git Orientation (Always Do This)
+
+Before any other work, run:
+
+```bash
+# 1. Confirm current branch
+git branch --show-current
+
+# 2. Check how far ahead of target branch
+git rev-list --count main..HEAD
+
+# 3. Get a cheap summary of what's changed
+git diff main...HEAD --stat
+```
+
+Cross-reference the diff stat against the active project's `TODO.md`:
+- Changed files should map to ticked TODO items.
+- Unticked TODOs with no corresponding changed files = work not yet started.
+- Changed files with no corresponding TODO = untracked work, worth noting.
+
+If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
+
+If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
+
+---
+
+## Cycle-End Review
+
+When all TODOs are ticked:
+
+1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
+2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
+   ```bash
+   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+     --output .ai-assistance/projects/<slug>/gemini_review.txt \
+     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
+   ```
+3. Review Gemini's output — verify each claim against actual code before acting.
+4. Propose fixes for genuine issues — confirm with developer.
+5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
+6. Update `INTENT.md` status to `complete`.
+7. Prompt: "Ready to open the MR / start the next project?"
+
+---
+
+## Upstream Dependency Changes
+
+If changes require modifying an upstream gem:
+
+Options (present all three to developer):
+
+1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
+2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
+3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
+
+Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
+
+---
+
+## Session / Collaborator Setup (First Time on a Machine)
+
+When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
+
+1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
+
+2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
+
+   | Gem | Remote |
+   |-----|--------|
+   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
+   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
+   | `graphlient` | https://github.com/rellampec/graphlient.git |
+   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
+   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
+
+3. For each one they have locally:
+   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
+   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
+
+4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
+
+5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
+
+6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
+
+If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"

data/.ai-assistance/skills/refactor/SKILL.md

@@ -1,62 +1,62 @@
-# SKILL: Refactor
-
-**Purpose:** Identify, log, and (with developer confirmation) apply refactoring opportunities. Never apply changes without explicit confirmation.
-
----
-
-## When to Use
-
-- You notice a structural issue while working on something else — log it, don't fix it silently.
-- The developer asks for a refactor audit of an area.
-- A cycle-end review surfaces cleanup opportunities.
-
----
-
-## Criteria for a Refactor Candidate
-
-Flag something when it fails one or more of:
-
-- **Understandability:** Is it clear what this does and why?
-- **Dependency tracking:** Are dependencies implicit or tangled?
-- **Separation of concerns:** Is this class/method doing more than one thing?
-- **Simplicity:** Could this be simpler without losing correctness?
-- **Alignment:** Does this match the conventions of the rest of the codebase?
-
----
-
-## Log Format
-
-Refactoring opportunities are logged in `.ai-assistance/code/refactoring/<area>.md`.
-
-Each entry:
-
-```markdown
-## [SHORT-ID] <Title>
-
-- **File(s):** `lib/ecoportal/...`
-- **Type:** [extract_class | extract_method | rename | simplify | reorganise | other]
-- **Priority:** [high | medium | low]
-- **Status:** [open | confirmed | applied | dismissed]
-- **Identified:** YYYY-MM-DD
-
-**Observation:**
-What the issue is, concisely.
-
-**Proposed change:**
-What you'd do to fix it. High-level — not code unless it's very short.
-
-**Risk:**
-Any backwards-compat or downstream risk if applied.
-```
-
----
-
-## Workflow
-
-1. Identify opportunity → log it in the appropriate refactoring file.
-2. Present a summary to the developer: "I've logged N refactoring opportunities in `.ai-assistance/code/refactoring/`. Want to review them?"
-3. Developer confirms which ones to apply → mark as `confirmed`.
-4. Apply one at a time, update specs if needed, mark as `applied`.
-5. If dismissed by developer → mark as `dismissed` with a brief reason.
-
-**Never apply a refactor without a `confirmed` status.**
+# SKILL: Refactor
+
+**Purpose:** Identify, log, and (with developer confirmation) apply refactoring opportunities. Never apply changes without explicit confirmation.
+
+---
+
+## When to Use
+
+- You notice a structural issue while working on something else — log it, don't fix it silently.
+- The developer asks for a refactor audit of an area.
+- A cycle-end review surfaces cleanup opportunities.
+
+---
+
+## Criteria for a Refactor Candidate
+
+Flag something when it fails one or more of:
+
+- **Understandability:** Is it clear what this does and why?
+- **Dependency tracking:** Are dependencies implicit or tangled?
+- **Separation of concerns:** Is this class/method doing more than one thing?
+- **Simplicity:** Could this be simpler without losing correctness?
+- **Alignment:** Does this match the conventions of the rest of the codebase?
+
+---
+
+## Log Format
+
+Refactoring opportunities are logged in `.ai-assistance/code/refactoring/<area>.md`.
+
+Each entry:
+
+```markdown
+## [SHORT-ID] <Title>
+
+- **File(s):** `lib/ecoportal/...`
+- **Type:** [extract_class | extract_method | rename | simplify | reorganise | other]
+- **Priority:** [high | medium | low]
+- **Status:** [open | confirmed | applied | dismissed]
+- **Identified:** YYYY-MM-DD
+
+**Observation:**
+What the issue is, concisely.
+
+**Proposed change:**
+What you'd do to fix it. High-level — not code unless it's very short.
+
+**Risk:**
+Any backwards-compat or downstream risk if applied.
+```
+
+---
+
+## Workflow
+
+1. Identify opportunity → log it in the appropriate refactoring file.
+2. Present a summary to the developer: "I've logged N refactoring opportunities in `.ai-assistance/code/refactoring/`. Want to review them?"
+3. Developer confirms which ones to apply → mark as `confirmed`.
+4. Apply one at a time, update specs if needed, mark as `applied`.
+5. If dismissed by developer → mark as `dismissed` with a brief reason.
+
+**Never apply a refactor without a `confirmed` status.**