gsd-pi 2.75.0 → 2.76.0

package/src/resources/extensions/gsd/workflow-templates/observability-setup.md

@@ -0,0 +1,133 @@
+# Observability Setup Workflow
+
+<template_meta>
+name: observability-setup
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/observability/
+</template_meta>
+
+<purpose>
+Add structured logging, metrics, and tracing to a project that has none (or
+not enough). Picks tools appropriate to the stack, instruments the
+highest-value code paths first, and verifies that operators can actually use
+the output to debug an incident.
+</purpose>
+
+<phases>
+1. survey    — Understand what exists, what's missing, and what we need
+2. design    — Pick tools + plan instrumentation
+3. implement — Add logs / metrics / traces to the prioritized paths
+4. verify    — Run a synthetic incident and confirm we'd catch it
+</phases>
+
+<process>
+
+## Phase 1: Survey
+
+**Goal:** Know the starting point so the plan is honest.
+
+1. **Inventory existing instrumentation:**
+   - Logging framework (winston / pino / logging / zap / ...)?
+   - Log destination (stdout / file / remote aggregator)?
+   - Existing metrics (Prometheus / OpenTelemetry / custom)?
+   - Existing traces (Jaeger / Zipkin / OTEL)?
+   - Error reporting (Sentry / Rollbar / ...)?
+
+2. **Identify the critical paths:**
+   - The top 3–5 user-facing flows.
+   - Any background jobs or schedulers.
+   - External dependencies (DBs, HTTP APIs, queues).
+
+3. **Classify each path:**
+   - Fully instrumented, partially, or not at all.
+   - What question would an operator want to answer about this path at 2 AM?
+
+4. **Write `SURVEY.md`:**
+   - Current state summary.
+   - Prioritized list of gaps (what's missing where).
+   - Constraints (budget, existing tooling, cloud provider).
+
+5. **Gate:** Confirm priorities. Observability work is easy to over-engineer —
+   focus on the top 3 paths rather than blanket coverage.
+
+## Phase 2: Design
+
+**Goal:** Pick tools and agree on conventions before coding.
+
+1. **Choose the stack:**
+   - **Logs:** structured JSON with a consistent schema (timestamp, level,
+     service, request_id, user_id when safe, message, fields).
+   - **Metrics:** counter / gauge / histogram; decide the naming scheme
+     (`<service>.<area>.<what>_<unit>`).
+   - **Traces:** OpenTelemetry is the modern default unless the project
+     is already committed to something else.
+
+2. **Define the conventions** and write them to `CONVENTIONS.md`:
+   - Log levels: when to use debug / info / warn / error.
+   - Trace naming: span names as `verb.object`.
+   - Metric labels: what's allowed, what's banned (high-cardinality warning).
+   - PII / secret-scrubbing rules — critical, document them.
+
+3. **Plan the instrumentation** — `PLAN.md`:
+   - For each critical path: what logs, what metrics, what trace spans.
+   - The order to implement (start with the highest-value path).
+
+4. **Gate:** Review the plan. Conventions are hard to change later — get them
+   right now.
+
+## Phase 3: Implement
+
+**Goal:** Ship instrumentation one path at a time.
+
+1. **Bootstrap the libraries:**
+   - Install chosen packages.
+   - Create a shared `observability.ts` / `observability.py` module:
+     logger factory, metric registry, tracer setup.
+   - Add env-based configuration (log level, trace sampling, metrics endpoint).
+
+2. **Instrument one critical path end-to-end:**
+   - Entry-point log with all relevant context.
+   - Key decision points logged at debug level.
+   - Outbound calls wrapped in a trace span.
+   - Errors logged at error level with stack traces.
+   - Counter + histogram for the operation.
+
+3. **Commit atomically** — one path per commit. Run the path and inspect the
+   output to make sure it's actually useful.
+
+4. **Repeat** for the remaining prioritized paths.
+
+5. **Write `IMPL.md`** as you go, noting anything that surprised you or that
+   operators should know.
+
+## Phase 4: Verify
+
+**Goal:** Prove that we'd catch a real incident.
+
+1. **Run a synthetic incident:**
+   - Inject a failure (kill the DB connection, throw a timeout, slow down
+     a dependency).
+   - From the logs / metrics / traces alone, could an operator who didn't
+     write the code diagnose it?
+
+2. **Fix the gaps** surfaced by the drill — usually missing context in
+   error logs, or metrics that don't label the failure mode.
+
+3. **Write `VERIFY.md`:**
+   - What scenarios were tested.
+   - What was observable vs what wasn't.
+   - Recommended alerts to set up (thresholds, not tools).
+
+4. **Document for operators** — update the runbook or README "operating"
+   section:
+   - Where logs go.
+   - How to view traces.
+   - Key metrics and their healthy ranges.
+
+5. **Gate:** Final review. Observability that nobody uses is overhead, not
+   value — the user should be able to demo "here's how I'd debug X" using
+   the new instrumentation.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/onboarding-check.md

@@ -0,0 +1,74 @@
+# Onboarding Check
+
+<template_meta>
+name: onboarding-check
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Walk the project's README end-to-end as a brand-new contributor would, and
+report every step that fails, is unclear, or is missing. Oneshot — produce a
+gap report, not a fix.
+</purpose>
+
+<instructions>
+
+## 1. Read the README top-to-bottom
+
+- Read `README.md` (and any `CONTRIBUTING.md`, `docs/setup.md`, or other
+  docs the README links from its "Getting Started" section).
+- Make a list of every command the docs tell you to run, in order.
+
+## 2. Check the environment
+
+For each prerequisite the README claims ("Node ≥ 22", "Python 3.11",
+"Docker", etc.):
+- Check whether the version is stated.
+- Check whether it's pinned in the repo (e.g. `package.json` engines, `.nvmrc`,
+  `.tool-versions`, `pyproject.toml`, `Dockerfile`).
+- If the README's claim and the repo's pin disagree, flag it.
+
+## 3. Dry-run the commands
+
+Where safe, run the commands in the **current** environment:
+- `npm install` / `pip install -r requirements.txt` / equivalent.
+- The "build" / "test" / "run" commands.
+- The "dev server" command (spawn, wait 5s, kill it).
+
+Skip any command that:
+- Would hit external APIs with credentials (record as "needs real creds, not tested").
+- Would incur real cost (cloud deploys, paid APIs).
+- Would modify global state (`sudo`, package manager global installs).
+
+## 4. Report
+
+```
+# Onboarding Report — <project name>
+
+## Summary
+<1–2 sentences: did a new contributor have a path that "just works"?>
+
+## Prerequisites
+- [✓/✗/?] <prereq> — <notes, version mismatch, etc.>
+
+## Steps
+1. [✓/✗/?] <command> — <exit code, error, or output snippet>
+
+## Gaps
+- <missing docs>
+- <commands that failed or produced surprising output>
+- <undocumented side effects>
+
+## Recommendations
+- <specific README edits that would fix the top 3 gaps>
+```
+
+## 5. Don't edit
+
+Don't modify the README or any config — just report. The author decides which
+gaps to close.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/performance-audit.md

@@ -0,0 +1,125 @@
+# Performance Audit Workflow
+
+<template_meta>
+name: performance-audit
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/perf/
+</template_meta>
+
+<purpose>
+Find and fix real performance problems. Measure first, fix with evidence,
+measure again. Avoids the common trap of "optimizations" that don't move
+actual user-facing metrics.
+</purpose>
+
+<phases>
+1. profile     — Gather real measurements from representative workloads
+2. prioritize  — Pick the fixes with the best effort/impact ratio
+3. fix         — Apply the changes with before/after numbers
+4. verify      — Confirm the improvements hold under realistic load
+</phases>
+
+<process>
+
+## Phase 1: Profile
+
+**Goal:** Replace intuition with measurements.
+
+1. **Define the workload.** What's slow, for whom, and under what conditions?
+   - Interactive: which user flow?
+   - Batch: which job?
+   - API: which endpoint, at what QPS?
+   Without this, you're optimizing in the dark.
+
+2. **Establish a baseline metric** that reflects what users feel:
+   - Latency at p50, p95, p99.
+   - Throughput.
+   - Memory high-water-mark.
+   - Cold-start / warm-start times.
+   Pick one or two metrics — not all five.
+
+3. **Run a profiler.**
+   - Node: `node --prof`, `clinic.js`, Chrome DevTools flamegraphs.
+   - Python: `cProfile`, `py-spy`, `scalene`.
+   - Go: `pprof`.
+   - Web: Lighthouse, Chrome Performance tab, Web Vitals.
+   - Database: `EXPLAIN ANALYZE`, slow query log.
+
+4. **Write `BASELINE.md`** with:
+   - Exact workload description (so we can re-run it).
+   - Metric values.
+   - Profile output or flamegraph attached.
+   - Top 5 hot functions / queries / network calls.
+
+5. **Gate:** The user confirms the baseline matches their experience. If it
+   doesn't, the workload isn't representative — go back and fix that first.
+
+## Phase 2: Prioritize
+
+**Goal:** Pick the fixes that actually matter.
+
+1. **For each hot spot in the profile**, estimate:
+   - Potential improvement (guesstimate the % reduction).
+   - Implementation effort (hours / days).
+   - Risk (probability of introducing bugs).
+
+2. **Prioritize by impact / (effort × risk).** A 50% reduction in a
+   p99-tail function often beats a 90% reduction in a warm path.
+
+3. **Write `PLAN.md`** with:
+   - A ranked list of fixes (top 3–5).
+   - For each: what changes, why it should help, what could go wrong.
+   - Explicitly call out hot spots you're choosing to SKIP and why.
+
+4. **Gate:** Confirm the plan with the user before coding. It's cheap to
+   change direction here, expensive later.
+
+## Phase 3: Fix
+
+**Goal:** Apply changes with receipts.
+
+1. **One fix at a time.** Each becomes an atomic commit. Don't bundle
+   unrelated perf changes — you'll lose the ability to attribute gains.
+
+2. **Before/after measurement** for each fix:
+   - Run the same workload from Phase 1.
+   - Record the new metrics.
+   - If a fix doesn't help, revert it and say so.
+
+3. **Commit message format:**
+   ```
+   perf(<area>): <change summary>
+
+   Before: p95 400ms
+   After:  p95 180ms
+   ```
+
+4. **Append to `PROGRESS.md`:**
+   - Fix name, before/after, whether kept or reverted.
+
+## Phase 4: Verify
+
+**Goal:** Make sure the improvements hold up in reality.
+
+1. **Re-run the full Phase 1 workload.** Compare against baseline.
+
+2. **Test under stress** — 2x the normal load, cold caches, realistic data
+   sizes. Perf fixes that only help a synthetic microbenchmark aren't
+   worth shipping.
+
+3. **Check for regressions** elsewhere — run the full test suite, watch
+   memory, check other endpoints. Sometimes local gains come with global
+   costs.
+
+4. **Write `REPORT.md`:**
+   - Summary: which metric improved by how much, and under what conditions.
+   - Fixes kept vs reverted.
+   - Remaining hot spots that weren't worth it.
+   - Monitoring recommendation: what metric to track so regressions surface.
+
+5. **Gate:** Present the report. If the improvement isn't meaningful at the
+   user-facing level, that's important to surface — don't pretend a win.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/pr-review.md

@@ -0,0 +1,67 @@
+# PR Review
+
+<template_meta>
+name: pr-review
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Produce a structured code-review for the current branch's diff (or a named PR
+if the user supplies one). No branch switching, no state tracking — emit the
+review as a single response and stop.
+</purpose>
+
+<instructions>
+
+## 1. Determine what to review
+
+- If the user arguments include a PR number (e.g. `#123`) or a URL matching
+  `github.com/<owner>/<repo>/pull/<n>`, use `gh pr view <ref>` + `gh pr diff <ref>`.
+- Otherwise, default to the current branch vs `main`: `git diff main...HEAD`.
+- If neither has changes, say so and stop.
+
+## 2. Survey the diff
+
+- List the files touched, grouped into: `src/`, `tests/`, `docs/`, `config/`, `other`.
+- For each file, note what kind of change it is (feature, refactor, fix, test, docs).
+- Flag anything that looks unusual for its directory (e.g. `.env` changes,
+  generated files, lockfiles with semver-major bumps).
+
+## 3. Produce the review
+
+Structure the output as:
+
+```
+## Summary
+<2–3 sentence overview of what the PR does>
+
+## Concerns
+- <specific line references for anything that could break, regress, or harm
+  maintainability. Prefer `file.ts:42` anchors. Omit this section if none.>
+
+## Suggestions
+- <non-blocking improvements — naming, tests to add, small refactors>
+
+## Tests / Verification
+- <what tests were added? anything uncovered? did CI run?>
+
+## Questions
+- <open questions you can't answer from the diff alone>
+```
+
+## 4. Be concrete
+
+- Quote 1–3 specific lines with `file:line` references in each bullet where
+  applicable. Vague reviews ("consider refactoring this") are worse than none.
+- If the diff is >500 lines, call out that and ask whether to do a deep review
+  or a skim — don't silently skim a large diff.
+
+## 5. Don't modify code
+
+This is a oneshot review. Do **not** edit files or create artifacts. If you
+suggest a change, describe it in prose — let the author decide.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/pr-triage.md

@@ -0,0 +1,83 @@
+# PR Triage
+
+<template_meta>
+name: pr-triage
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Walk open pull requests and produce a triage report: which to merge, close,
+or nudge. Oneshot — report only, no actions taken.
+</purpose>
+
+<instructions>
+
+## 1. List open PRs
+
+Run `gh pr list --state open --limit 50 --json number,title,author,createdAt,updatedAt,isDraft,labels,reviewDecision,mergeable,headRefName,statusCheckRollup,additions,deletions`.
+
+If there are more than 50 open PRs, note that and use `--limit 100`. If still
+more, just pick the 100 most recently updated and warn that the report is
+partial.
+
+## 2. Bucket each PR
+
+For each PR, compute:
+- **Age**: days since creation.
+- **Staleness**: days since last update.
+- **Size**: `additions + deletions` (small ≤ 100, medium ≤ 500, large > 500).
+- **CI**: passing, failing, pending, none.
+- **Reviews**: approved, changes-requested, pending, none.
+- **Mergeability**: clean, conflicting, unknown.
+- **Draft**: yes/no.
+
+Put each PR into exactly ONE bucket:
+
+- **✅ Ready to merge** — non-draft, approved, CI passing, mergeable.
+- **🛠 Waiting on author** — changes-requested or CI failing.
+- **👀 Needs review** — no reviews, non-draft, CI passing, ≤ 30 days old.
+- **💤 Stale** — no update in 30+ days.
+- **❌ Close candidate** — stale > 90 days AND (no reviews OR conflicting)
+  OR author is inactive OR scope is clearly superseded.
+- **🚧 Draft** — explicitly drafted, not yet ready.
+
+## 3. Output
+
+```
+PR Triage — <N> open PRs (as of YYYY-MM-DD)
+
+## ✅ Ready to merge (<n>)
+- #123 <title> — by @author, +X/-Y, approved, CI ✓
+  Next: merge with `gh pr merge 123`.
+
+## 🛠 Waiting on author (<n>)
+- #124 <title> — CI failing: <reason>. Nudge author.
+
+## 👀 Needs review (<n>)
+- #125 <title> — 5 days old, no reviews yet.
+
+## 💤 Stale (<n>)
+- #126 <title> — no update in 45 days. Suggest: nudge @author, or close.
+
+## ❌ Close candidates (<n>)
+- #127 <title> — 120 days stale, conflicts with main, superseded by #140.
+
+## 🚧 Drafts (<n>)
+- #128 — <title>
+```
+
+## 4. Recommend specific actions
+
+At the bottom, produce a short action list of the top 3–5 PRs that would have
+the biggest impact if resolved (oldest bottlenecking, most approved but unmerged,
+easiest close-candidates).
+
+## 5. Don't act
+
+Do not run `gh pr merge`, `gh pr close`, or `gh pr comment`. The report is
+for humans to act on.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/refactor.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: refactor
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/refactors/
 </template_meta>