@codyswann/lisa 2.121.0 → 2.122.0

package/plugins/lisa-rails-copilot/skills/jira-add-journey/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: jira-add-journey
+description: "Add a Validation Journey section to an existing JIRA ticket by reading the ticket description, understanding the feature, and generating the journey steps and assertions."
+---
+
+# Add Validation Journey to Existing JIRA Ticket
+
+Read an existing JIRA ticket, understand the feature or fix it describes, analyze the codebase to determine the verification approach, and append a Validation Journey section to the ticket description.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`)
+
+## Workflow
+
+### Step 1: Read the Ticket
+
+Use the Atlassian MCP or jira-cli to read the full ticket details:
+
+```bash
+jira issue view <TICKET_ID>
+```
+
+Extract: title, description, acceptance criteria, components, labels, linked tickets.
+
+### Step 2: Check for Existing Journey
+
+Run the parser to see if a Validation Journey already exists:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID> 2>&1
+```
+
+If the parser succeeds and returns steps, the ticket already has a journey. Report this to the user and stop.
+
+### Step 3: Analyze the Feature
+
+Based on the ticket description and acceptance criteria, determine the appropriate verification approach. Stack-specific overrides provide the analysis logic.
+
+### Step 4: Draft the Validation Journey
+
+Compose the journey following the Validation Journey format with: Prerequisites, Steps (with evidence markers), and Assertions.
+
+### Step 5: Present to User for Approval
+
+Display the drafted Validation Journey to the user and ask for confirmation before appending it to the ticket.
+
+### Step 6: Append to Ticket Description
+
+After user approval, use the JIRA REST API to append the Validation Journey to the existing ticket description.
+
+### Step 7: Verify
+
+Run the parser again to confirm the journey was added correctly:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```

package/plugins/lisa-rails-copilot/skills/jira-create/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: jira-create
+description: This skill should be used when creating JIRA epics, stories, and tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation.
+allowed-tools: ["Read", "Glob", "LS", "Skill", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+Analyze the provided file(s) and plan a JIRA hierarchy. **This skill plans structure only — every individual ticket write is delegated to `lisa:jira-write-ticket`.** Do not call `mcp__atlassian__createJiraIssue` from this skill; the necessary write tools are intentionally not in `allowed-tools`.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope.
+2. **Extract source artifacts**: invoke the `lisa:tracker-source-artifacts` skill, then enumerate every external URL, embed, attachment, or example payload and classify each by domain per its rules. Build the `artifacts` map. See "Source Artifacts" below.
+3. **Walk the live product** (when applicable): if the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill to capture current behavior, design-vs-product divergence, and reuse candidates. Skip only when the work is purely backend or affects a screen that does not yet exist. See "Live Product Walkthrough" below.
+4. **Determine structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+5. **Plan hierarchy**:
+   ```text
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+6. **Delegate every write to `lisa:jira-write-ticket`** in dependency order (epic first, then stories with the epic as parent, then sub-tasks with their story as parent). Pass the artifacts (filtered by domain per `lisa:tracker-source-artifacts` inheritance rules) and the walkthrough findings (under `## Current Product`). See "Delegation to jira-write-ticket" below.
+7. **Run the artifact preservation gate** (`lisa:tracker-source-artifacts` §8): after all writes complete, build the preservation matrix and verify every extracted artifact is reachable from the created tickets. Fail loudly if anything was dropped.
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Feature Flags**: All features behind flags with lifecycle plan
+**Cleanup**: Remove temporary code, scripts, dev configs
+
+## Source Artifacts
+
+If $ARGUMENTS includes (or references) any external artifact — PRD, design doc, Figma URL, Lovable prototype, Loom walkthrough, screenshot, example payload — those references MUST be preserved as remote links on the created tickets. Silent artifact loss is the single most common quality failure in this pipeline.
+
+**Invoke the `lisa:tracker-source-artifacts` skill** for the canonical rules: domains, per-tool classification (Figma `/proto/` vs design, Lovable, Loom, screenshots), source precedence, conflict handling under `## Open Questions`, inheritance from epic → story → sub-task, and the existing-component reuse expectation. Do not restate the rules here.
+
+Rails-specific note: the existing-component reuse rule applies to view partials and ViewComponents — the closest existing partial/component is usually the right answer over pixel-matching a mock from scratch.
+
+When delegating writes to `lisa:jira-write-ticket`, pass the extracted artifact list so its Phase 4c step can attach them.
+
+## Live Product Walkthrough
+
+When the work touches existing user-facing surfaces, invoke the `lisa:product-walkthrough` skill before drafting tickets. Findings (current behavior, design-vs-product divergence, reuse candidates, behavioral surprises) become inputs to the ticket plan and surface under `## Current Product` on the resulting tickets. Skip only when the work is purely backend or affects a screen that does not yet exist.
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: SE (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+## Delegation to jira-write-ticket
+
+**Mandatory.** Every ticket created by this skill MUST go through `lisa:jira-write-ticket`. This skill never calls `mcp__atlassian__createJiraIssue` itself — that tool is intentionally excluded from `allowed-tools` so the gate cannot be bypassed.
+
+`lisa:jira-write-ticket` enforces things this skill does not, and which determine ticket quality:
+- 3-audience description (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Epic parent validation (non-bug, non-epic types)
+- Explicit link discovery (`blocks` / `is blocked by` / `relates to` / `duplicates` / `clones`)
+- Remote links (PRs, Confluence, dashboards)
+- Single-repo scope check for Bug / Task / Sub-task
+- Sign-in account and target environment recorded in description
+- Post-create verification
+
+### Invocation order
+
+Tickets must be created in parent-before-child order so each child can be passed its parent key:
+
+1. Invoke `lisa:jira-write-ticket` for the epic. Capture the returned key.
+2. For each story, invoke `lisa:jira-write-ticket` with the epic key as the epic parent. Capture each story key.
+3. For each sub-task, invoke `lisa:jira-write-ticket` with the parent story key.
+
+### What to pass to each invocation
+
+For every delegated write, pass:
+- The summary, issue type, project key, and priority you decided
+- The 3-section description body you drafted (Context / Technical Approach / Acceptance Criteria)
+- Gherkin acceptance criteria
+- Parent key (epic key for stories; story key for sub-tasks)
+- The artifact list extracted in "Source Artifacts", filtered by domain per the inheritance rules — `lisa:jira-write-ticket` Phase 4c attaches them as remote links
+- For tickets that change runtime behavior: the Validation Journey draft, or instruct it to call `lisa:jira-add-journey` after create
+
+### What this skill is responsible for
+
+This skill owns:
+- Deciding the *shape* of the hierarchy (what's an epic vs. story vs. sub-task)
+- Drafting the description body and acceptance criteria from the input
+- Extracting and classifying source artifacts
+- Threading parent keys through subsequent writes
+- Running the artifact preservation check after all writes complete
+
+It does not own the actual JIRA write — that's `lisa:jira-write-ticket`'s job.

package/plugins/lisa-rails-copilot/skills/jira-evidence/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: jira-evidence
+description: "Upload evidence to GitHub pr-assets release, update PR description, upload attachments to JIRA, post comment, and move ticket to Code Review. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/comment.md."
+---
+
+# JIRA Evidence Posting
+
+Upload captured evidence and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes evidence files and comment templates already exist in the evidence directory.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `EVIDENCE_DIR` (required): Directory containing evidence and templates (e.g., `./evidence`)
+- `PR_NUMBER` (required): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`) — server and login are read from there
+- `gh` CLI authenticated
+- Evidence directory containing:
+  - Evidence files: `NN-name-viewport.png` (screenshots) and/or `NN-name.txt`/`NN-name.json` (text evidence)
+  - `comment.txt` — JIRA wiki markup (generated by `generate-templates.py`)
+  - `comment.md` — GitHub markdown (generated by `generate-templates.py`)
+
+## Usage
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+```
+
+### Example
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh PROJ-123 ./evidence 42
+```
+
+## What It Does
+
+1. **Read JIRA config** — Reads `~/.config/.jira/.config.yml` to obtain `server` and `login` dynamically (no hardcoded values)
+2. **Upload to GitHub `pr-assets` release** — Uploads evidence files via `gh release upload --clobber`, creating CDN URLs
+3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body using `gh pr edit`
+4. **Upload JIRA attachments** — Uploads image evidence via REST API v3 so `!filename.png!` wiki markup renders inline
+5. **Post JIRA comment** — Posts `comment.txt` as a new comment via REST API v2 (wiki markup)
+6. **Move ticket to Code Review** — Transitions the JIRA ticket via `jira issue move`
+
+## Evidence Naming Conventions
+
+- Image evidence: `NN-name-viewport.png` (e.g., `01-search-step-desktop.png`)
+- Text evidence: `NN-name.txt` or `NN-name.json` (e.g., `01-health-check.json`)
+
+## Troubleshooting
+
+### Images not rendering in GitHub PR
+
+Images must be in the `pr-assets` GitHub release. If the release does not exist, create it first:
+
+```bash
+gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence"
+```
+
+### JIRA comment shows `!filename.png!` as text (not image)
+
+The screenshot must be uploaded as a JIRA attachment before posting the comment. The script uploads attachments first then posts the comment.
+
+### JIRA API returns 403 on attachment upload
+
+Ensure `JIRA_API_TOKEN` is set and `login` in `~/.config/.jira/.config.yml` matches your Atlassian account email.

package/plugins/lisa-rails-copilot/skills/jira-evidence/scripts/post-evidence.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# post-evidence.sh — Upload evidence and post to JIRA + GitHub PR description
+#
+# Usage:
+#   bash post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+#
+# Prerequisites:
+#   - JIRA_API_TOKEN env var set
+#   - jira-cli configured (~/.config/.jira/.config.yml)
+#   - gh CLI authenticated
+#
+# What it does:
+#   1. Uploads evidence files to the 'pr-assets' GitHub release
+#   2. Updates the GitHub PR description with evidence/comment.md
+#   3. Uploads image evidence as JIRA attachments
+#   4. Posts/updates the JIRA comment with evidence/comment.txt
+#   5. Moves the JIRA ticket to "Code Review"
+
+set -euo pipefail
+
+TICKET_ID="${1:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+EVIDENCE_DIR="${2:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+PR_NUMBER="${3:?Usage: post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>}"
+
+JIRA_CONFIG="${HOME}/.config/.jira/.config.yml"
+if [[ ! -f "$JIRA_CONFIG" ]]; then
+  echo "ERROR: jira-cli config not found at $JIRA_CONFIG — run 'jira init' first" >&2
+  exit 1
+fi
+JIRA_SERVER=$(grep '^server:' "$JIRA_CONFIG" | awk '{print $2}')
+JIRA_USER=$(grep '^login:' "$JIRA_CONFIG" | awk '{print $2}')
+GH_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+RELEASE_TAG="pr-assets"
+
+if [[ -z "${JIRA_API_TOKEN:-}" ]]; then
+  echo "ERROR: JIRA_API_TOKEN environment variable is not set" >&2
+  exit 1
+fi
+
+# Collect numbered evidence files (images + text)
+SCREENSHOTS=()
+while IFS= read -r -d '' f; do
+  SCREENSHOTS+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 -name '[0-9][0-9]-*.png' -print0 | sort -z)
+
+TEXT_EVIDENCE=()
+while IFS= read -r -d '' f; do
+  TEXT_EVIDENCE+=("$f")
+done < <(find "$EVIDENCE_DIR" -maxdepth 1 \( -name '[0-9][0-9]-*.txt' -o -name '[0-9][0-9]-*.json' \) ! -name 'comment.txt' -print0 | sort -z)
+
+ALL_EVIDENCE=("${SCREENSHOTS[@]}" "${TEXT_EVIDENCE[@]}")
+
+if [[ ${#ALL_EVIDENCE[@]} -eq 0 ]]; then
+  echo "ERROR: No numbered evidence files found in $EVIDENCE_DIR (expected NN-*.png, NN-*.txt, or NN-*.json)" >&2
+  exit 1
+fi
+
+echo "Found ${#SCREENSHOTS[@]} screenshots and ${#TEXT_EVIDENCE[@]} text evidence files to upload"
+
+# Compute JIRA auth early (used in steps 3 and 4)
+JIRA_AUTH=$(echo -n "$JIRA_USER:$JIRA_API_TOKEN" | base64)
+
+# ── Step 1: Upload to GitHub pr-assets release ──────────────────────────────
+echo ""
+echo "==> Uploading to GitHub release '$RELEASE_TAG'..."
+
+for FILE in "${ALL_EVIDENCE[@]}"; do
+  FILENAME=$(basename "$FILE")
+  echo "  ↑ $FILENAME"
+  gh release upload "$RELEASE_TAG" "$FILE" --repo "$GH_REPO" --clobber
+done
+
+echo "  ✓ GitHub release assets uploaded"
+
+# ── Step 2: Update GitHub PR description with evidence ──────────────────────
+COMMENT_MD="$EVIDENCE_DIR/comment.md"
+if [[ ! -f "$COMMENT_MD" ]]; then
+  echo "ERROR: $COMMENT_MD not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Updating GitHub PR #$PR_NUMBER description..."
+
+CURRENT_BODY=$(gh pr view "$PR_NUMBER" --json body --jq '.body')
+
+# Replace or append the Evidence section
+if echo "$CURRENT_BODY" | grep -q "^## Evidence"; then
+  # Replace from "## Evidence" to end of file
+  NEW_BODY=$(echo "$CURRENT_BODY" | sed '/^## Evidence/,$d')
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${NEW_BODY}
+${EVIDENCE_SECTION}"
+else
+  EVIDENCE_SECTION=$(cat "$COMMENT_MD")
+  UPDATED_BODY="${CURRENT_BODY}
+
+${EVIDENCE_SECTION}"
+fi
+
+gh pr edit "$PR_NUMBER" --body "$UPDATED_BODY"
+echo "  ✓ PR description updated with evidence"
+
+# ── Step 3: Upload image evidence as JIRA attachments ───────────────────────
+if [[ ${#SCREENSHOTS[@]} -gt 0 ]]; then
+  echo ""
+  echo "==> Uploading image attachments to JIRA $TICKET_ID..."
+
+  for IMG in "${SCREENSHOTS[@]}"; do
+    FILENAME=$(basename "$IMG")
+    echo "  ↑ $FILENAME"
+    RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+      -X POST \
+      -H "Authorization: Basic $JIRA_AUTH" \
+      -H "X-Atlassian-Token: no-check" \
+      -F "file=@$IMG" \
+      "$JIRA_SERVER/rest/api/3/issue/$TICKET_ID/attachments")
+    HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+    if [[ "$HTTP_CODE" != "200" ]]; then
+      echo "  WARNING: Failed to upload $FILENAME (HTTP $HTTP_CODE)" >&2
+    fi
+  done
+
+  echo "  ✓ JIRA attachments uploaded"
+fi
+
+# ── Step 4: Post JIRA comment ────────────────────────────────────────────────
+COMMENT_TXT="$EVIDENCE_DIR/comment.txt"
+if [[ ! -f "$COMMENT_TXT" ]]; then
+  echo "ERROR: $COMMENT_TXT not found — run generate-templates.py first" >&2
+  exit 1
+fi
+
+echo ""
+echo "==> Posting JIRA comment on $TICKET_ID..."
+
+COMMENT_BODY=$(cat "$COMMENT_TXT")
+COMMENT_JSON=$(python3 -c "import sys, json; print(json.dumps(sys.stdin.read()))" <<< "$COMMENT_BODY")
+
+RESP=$(curl -s -w "\nHTTP_CODE:%{http_code}" \
+  -X POST \
+  -H "Authorization: Basic $JIRA_AUTH" \
+  -H "Content-Type: application/json" \
+  "$JIRA_SERVER/rest/api/2/issue/$TICKET_ID/comment" \
+  -d "{\"body\": $COMMENT_JSON}")
+HTTP_CODE=$(echo "$RESP" | grep "HTTP_CODE:" | cut -d: -f2)
+
+if [[ "$HTTP_CODE" == "201" ]]; then
+  echo "  ✓ JIRA comment posted"
+else
+  echo "  WARNING: JIRA comment returned HTTP $HTTP_CODE" >&2
+  echo "$RESP" | grep -v "HTTP_CODE:" | head -3
+fi
+
+# ── Step 5: Move ticket to Code Review ──────────────────────────────────────
+echo ""
+echo "==> Moving $TICKET_ID to Code Review..."
+jira issue move "$TICKET_ID" "Code Review" 2>&1 && echo "  ✓ Ticket moved to Code Review" || echo "  WARNING: Could not move ticket" >&2
+
+echo ""
+echo "==> Done!"
+echo "    JIRA:   $JIRA_SERVER/browse/$TICKET_ID"
+echo "    GitHub: https://github.com/$GH_REPO/pull/$PR_NUMBER"

package/plugins/lisa-rails-copilot/skills/jira-journey/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: jira-journey
+description: "Parse a JIRA ticket's Validation Journey section, execute the verification steps, capture evidence, and post to JIRA + GitHub PR using the jira-evidence skill."
+---
+
+# JIRA Validation Journey
+
+Parse a JIRA ticket's Validation Journey, execute the verification steps using the project's appropriate tools, capture evidence at each marker, and post to JIRA + GitHub PR.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> [PR_NUMBER]`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `PR_NUMBER` (optional): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`)
+- `gh` CLI authenticated
+
+## Workflow
+
+### Step 1: Parse the Validation Journey
+
+Run the parser script to extract the Validation Journey from the JIRA ticket description:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```
+
+The script outputs JSON with: `ticket`, `prerequisites`, `steps`, `viewports`, `assertions`.
+
+### Step 2: Satisfy Prerequisites
+
+Before starting the journey, verify each prerequisite listed in the parsed output.
+
+### Step 3: Execute Steps
+
+Execute each step sequentially. At each step with an evidence marker (`[SCREENSHOT: name]` or `[EVIDENCE: name]`), capture the appropriate evidence.
+
+The execution method depends on the project type:
+- **UI projects**: Use Playwright MCP browser tools, capture screenshots at each viewport
+- **API projects**: Use curl or test commands, capture stdout/stderr
+- **Library projects**: Run tests, capture output
+
+Stack-specific overrides provide the actual execution implementation.
+
+### Step 4: Generate Evidence Templates
+
+After capturing all evidence, run the template generator to format evidence for JIRA and GitHub.
+
+### Step 5: Post Evidence
+
+Use the `/jira-evidence` skill to post everything:
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> ./evidence <PR_NUMBER>
+```
+
+### Step 6: Verify
+
+Confirm evidence renders at both the JIRA ticket and GitHub PR.

package/plugins/lisa-rails-copilot/skills/jira-verify/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: jira-verify
+description: This skill should be used when verifying that a JIRA ticket meets organizational standards for epic relationships and description quality. It fetches the live ticket and delegates the gate checks to jira-validate-ticket so the bar matches what jira-write-ticket enforces pre-write.
+allowed-tools: ["Skill", "mcp__atlassian__getJiraIssue", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Verify JIRA Ticket: $ARGUMENTS
+
+Verify that the existing JIRA ticket `$ARGUMENTS` meets organizational standards. This skill is a thin post-write wrapper around `lisa:jira-validate-ticket`: it fetches the live ticket and asks `lisa:jira-validate-ticket` to run the gates against the fetched state.
+
+This indirection exists so the gate definitions live in exactly one place (`lisa:jira-validate-ticket`). When the bar changes, change it there — `lisa:jira-verify`, `lisa:jira-write-ticket` (Phase 5.5 pre-write), and `lisa:notion-to-tracker` (PRD dry-run) all pick it up.
+
+## Process
+
+1. Resolve cloud ID via `mcp__atlassian__getAccessibleAtlassianResources`.
+2. Fetch the ticket via `mcp__atlassian__getJiraIssue` for `$ARGUMENTS`.
+3. Invoke `lisa:jira-validate-ticket` and pass the ticket key. The validator runs every gate (Specification + Feasibility) against the live state.
+4. Surface the validator's report verbatim.
+
+## Output
+
+Pass through `lisa:jira-validate-ticket`'s structured output unchanged. Downstream callers parse the gate lines.
+
+## Notes
+
+- This skill is read-only. It never edits the ticket, posts comments, or changes status.

package/plugins/lisa-rails-copilot/skills/ops-check-logs/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: ops-check-logs
+description: Check application logs from local Docker Compose or remote AWS CloudWatch for Rails applications. Supports log tailing, filtering, and error searching.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Check Logs
+
+View and search logs across local and remote environments.
+
+**Argument**: `$ARGUMENTS` — target and optional filter (e.g., `local`, `local worker`, `staging errors`, `production 500`, `staging slow-queries`)
+
+## Discovery
+
+1. Read `config/deploy.yml` to discover the service name (used in CloudWatch log group naming)
+2. Read `docker-compose.yml` to identify local service names for targeted log viewing
+3. Discover the AWS region from deploy config or environment variables
+
+## Local Logs (Docker Compose)
+
+### All Services
+
+```bash
+docker compose logs --tail=100
+```
+
+### Follow Mode (tail)
+
+```bash
+docker compose logs -f --tail=50
+```
+
+### Specific Service
+
+```bash
+# Rails web server
+docker compose logs --tail=100 web
+
+# Solid Queue worker
+docker compose logs --tail=100 worker
+
+# PostgreSQL
+docker compose logs --tail=100 postgres
+```
+
+### Filter for Errors
+
+```bash
+docker compose logs --tail=500 web 2>&1 | grep -iE "(error|exception|fatal|500)"
+```
+
+### Rails Development Log (if running outside Docker)
+
+```bash
+tail -n 100 log/development.log
+```
+
+### Filter Rails Log for Slow Queries
+
+```bash
+grep -E "SLOW|ms\)" log/development.log | tail -20
+```
+
+## Remote Logs (Kamal)
+
+### Tail Application Logs
+
+```bash
+kamal app logs -d {environment}
+```
+
+### Follow Mode
+
+```bash
+kamal app logs -d {environment} -f
+```
+
+### Specific Role
+
+```bash
+# Web role
+kamal app logs --roles=web -d {environment}
+
+# Worker role (Solid Queue)
+kamal app logs --roles=worker -d {environment}
+```
+
+## Remote Logs (CloudWatch via AWS CLI)
+
+For advanced filtering and historical log access, use the AWS CLI directly.
+
+### Discover Log Groups
+
+```bash
+aws logs describe-log-groups \
+  --region {aws-region} \
+  --query 'logGroups[].logGroupName' \
+  --output text | tr '\t' '\n' | grep -i "{app_name}"
+```
+
+### Filter for Errors (last 30 minutes)
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 1800) * 1000 )) \
+  --filter-pattern "ERROR" \
+  --query 'events[].message' \
+  --output text
+```
+
+### Filter for 500 Errors
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 1800) * 1000 )) \
+  --filter-pattern '"status=500"' \
+  --query 'events[].message' \
+  --output text
+```
+
+### Filter for Slow Requests (> 1 second)
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(( ($(date +%s) - 3600) * 1000 )) \
+  --filter-pattern '"duration" "1000"' \
+  --query 'events[].message' \
+  --output text
+```
+
+### Tail Live Logs
+
+```bash
+aws logs tail "{log-group}" \
+  --region {aws-region} \
+  --follow \
+  --since 10m
+```
+
+### Specific Time Range
+
+```bash
+aws logs filter-log-events \
+  --region {aws-region} \
+  --log-group-name "{log-group}" \
+  --start-time $(date -d "{start-time}" +%s000) \
+  --end-time $(date -d "{end-time}" +%s000) \
+  --query 'events[].message' \
+  --output text
+```
+
+## ECS Task Logs
+
+For container-level logs (useful when the application fails to start):
+
+```bash
+# List recent tasks
+aws ecs list-tasks \
+  --cluster {cluster-name} \
+  --service-name {service-name} \
+  --region {aws-region} \
+  --query 'taskArns[]' --output text
+
+# Describe a task to find the log stream
+aws ecs describe-tasks \
+  --cluster {cluster-name} \
+  --tasks {task-arn} \
+  --region {aws-region} \
+  --query 'tasks[0].containers[].{Name:name,Status:lastStatus,ExitCode:exitCode}' \
+  --output table
+```
+
+## Output Format
+
+Report log findings as:
+
+| Source | Timestamp | Level | Context | Message |
+|--------|-----------|-------|---------|---------|
+| CloudWatch | 2026-03-18T10:30:00Z | ERROR | web | ActiveRecord::ConnectionTimeoutError |
+| Docker | — | ERROR | worker | SolidQueue::ProcessMissingError |
+| Rails log | — | WARN | N/A | DEPRECATION WARNING: ... |
+
+Include a summary of findings: total errors, warnings, and any patterns observed.