This commit is contained in:
Jason Stedwell
@@ -1,68 +0,0 @@
|
|||||||
# Agent Operating Guide
|
|
||||||
|
|
||||||
Use this file as the first entrypoint for work in this repository.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions.
|
|
||||||
|
|
||||||
## Default Behavior
|
|
||||||
|
|
||||||
- Inspect the repository before making assumptions.
|
|
||||||
- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only.
|
|
||||||
- Read only the skill files needed for the current task.
|
|
||||||
- Reuse existing project patterns, naming, architecture, and conventions.
|
|
||||||
- Test or validate changes when feasible, then summarize outcomes and any remaining risks.
|
|
||||||
- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow.
|
|
||||||
- If repository-specific instructions conflict with this suite, follow the repository-specific instructions.
|
|
||||||
|
|
||||||
## How To Load Skills
|
|
||||||
|
|
||||||
1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment.
|
|
||||||
2. Read [SKILLS.md](./SKILLS.md).
|
|
||||||
3. Identify the task category and open the matching hub file.
|
|
||||||
4. Open only the specialized skill files relevant to the request.
|
|
||||||
5. Combine skills when the task spans multiple areas.
|
|
||||||
6. Avoid loading unrelated skills just because they exist.
|
|
||||||
|
|
||||||
## Context Economy Rules
|
|
||||||
|
|
||||||
- Default to reading one hub and two to four specialized skills for a normal task.
|
|
||||||
- Add more skills only when they materially change the approach, output, or quality bar.
|
|
||||||
- Prefer depth in the relevant skills over shallow loading across many categories.
|
|
||||||
- If two skills overlap heavily, choose the one that best matches the main risk or deliverable.
|
|
||||||
- Re-open the index when the task shifts, but do not reload the entire library reflexively.
|
|
||||||
- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area.
|
|
||||||
|
|
||||||
## Instruction Precedence
|
|
||||||
|
|
||||||
Apply guidance in this order:
|
|
||||||
|
|
||||||
1. Destination repository instructions
|
|
||||||
2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md)
|
|
||||||
3. Generic routing and skill guidance from this suite
|
|
||||||
|
|
||||||
## Routing Table
|
|
||||||
|
|
||||||
| Task type | Start here |
|
|
||||||
| --- | --- |
|
|
||||||
| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) |
|
|
||||||
| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) |
|
|
||||||
| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) |
|
|
||||||
| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) |
|
|
||||||
| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) |
|
|
||||||
| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) |
|
|
||||||
|
|
||||||
## Combination Rules
|
|
||||||
|
|
||||||
- For new features, combine implementation + test strategy + relevant docs.
|
|
||||||
- For UI work, combine frontend implementation + UX review + product copy when text matters.
|
|
||||||
- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands.
|
|
||||||
- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed.
|
|
||||||
- For high-risk changes, add security review, observability, or performance optimization as appropriate.
|
|
||||||
- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant.
|
|
||||||
|
|
||||||
## Output Expectations
|
|
||||||
|
|
||||||
- Deliver concrete work products, not just observations.
|
|
||||||
- State key assumptions when the repository does not answer them.
|
|
||||||
- Call out blockers, tradeoffs, risks, and unverified areas clearly.
|
|
||||||
- Keep explanations concise and action-oriented.
|
|
||||||
@@ -1,99 +0,0 @@
|
|||||||
# Deployment Profile
|
|
||||||
|
|
||||||
Use this file to stage prefilled defaults before deploying the suite into other repositories.
|
|
||||||
|
|
||||||
This file is the canonical source of preloaded build, tool, environment, workflow, and quality preferences for the deployed bundle. Keep it concise enough to be read early in a session.
|
|
||||||
|
|
||||||
## Precedence
|
|
||||||
|
|
||||||
1. Destination repository instructions
|
|
||||||
2. This deployment profile
|
|
||||||
3. Generic `AGENTS.md`, hubs, and skill files
|
|
||||||
|
|
||||||
## How To Maintain This File
|
|
||||||
|
|
||||||
- Fill out [PROJECT-PROFILE-WORKBOOK.md](./PROJECT-PROFILE-WORKBOOK.md) first.
|
|
||||||
- Rewrite the answers here as agent-facing defaults, not as questions.
|
|
||||||
- Prefer short, durable defaults over long policy prose.
|
|
||||||
- Update this file when your preferred build, tool, or workflow defaults change materially.
|
|
||||||
|
|
||||||
## Global Defaults
|
|
||||||
|
|
||||||
- Optimize first for full-stack web application repositories.
|
|
||||||
- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind.
|
|
||||||
- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist.
|
|
||||||
- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation.
|
|
||||||
- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
|
|
||||||
- Ask clarifying questions before meaningful changes when product intent or risk is unclear.
|
|
||||||
- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries.
|
|
||||||
- Hold user-facing work to a high polish bar by default.
|
|
||||||
- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant.
|
|
||||||
- Optimize hardest against regressions and broken behavior.
|
|
||||||
|
|
||||||
## Software Development Defaults
|
|
||||||
|
|
||||||
- Favor modular boundaries and cleaner separation early rather than waiting for severe pain.
|
|
||||||
- Operate as a full-stack agent by default and work comfortably across frontend and backend.
|
|
||||||
- Prefer mainstream modern patterns for the stack when multiple valid options exist.
|
|
||||||
- Assume relational databases first unless the repository clearly indicates otherwise.
|
|
||||||
- Be careful with schema and migration work, but do not overengineer small changes.
|
|
||||||
- Prefer small, safe, frequent dependency upgrades with focused validation.
|
|
||||||
- Treat performance as important early, especially on critical paths.
|
|
||||||
- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries.
|
|
||||||
- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems.
|
|
||||||
- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change.
|
|
||||||
|
|
||||||
## Debugging Defaults
|
|
||||||
|
|
||||||
- Start with the fastest trustworthy signal rather than forcing a single debugging order.
|
|
||||||
- Lean on logs and traces heavily before guessing.
|
|
||||||
- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced.
|
|
||||||
- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high.
|
|
||||||
- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition.
|
|
||||||
- Explain root cause clearly by connecting symptom, cause, and why the fix works.
|
|
||||||
- Avoid temporary compromises unless there is no safer path.
|
|
||||||
- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier.
|
|
||||||
|
|
||||||
## Documentation Defaults
|
|
||||||
|
|
||||||
- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary.
|
|
||||||
- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas.
|
|
||||||
- Create or update ADRs for major technical decisions and meaningful pattern shifts.
|
|
||||||
- Write concise, audience-aware change summaries that call out user impact when relevant.
|
|
||||||
- Maintain strong API and integration documentation by default for meaningful backend or interface work.
|
|
||||||
- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption.
|
|
||||||
- Update docs for any meaningful user-facing, setup, or team workflow change.
|
|
||||||
- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content.
|
|
||||||
|
|
||||||
## UI/UX Defaults
|
|
||||||
|
|
||||||
- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience.
|
|
||||||
- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it.
|
|
||||||
- Design responsively for both desktop and mobile by default.
|
|
||||||
- Reuse components when they fit well, and create new abstractions when they are likely to matter again.
|
|
||||||
- Hold interface copy to a highly polished product-copy standard by default.
|
|
||||||
- Use motion and visual flourish actively enough to make interfaces feel premium.
|
|
||||||
- Bias toward bold, distinctive UI within reason rather than purely conservative continuity.
|
|
||||||
- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed.
|
|
||||||
|
|
||||||
## Marketing Defaults
|
|
||||||
|
|
||||||
- Prioritize a mixed audience with a lean toward technical and product-savvy readers.
|
|
||||||
- Use a premium, distinctive, and persuasive voice.
|
|
||||||
- Keep marketing claims persuasive but grounded in real features and outcomes.
|
|
||||||
- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate.
|
|
||||||
- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity.
|
|
||||||
- Favor sharp, polished product copy with strong differentiation and clear calls to action.
|
|
||||||
- Frame positioning conservatively around real value rather than aggressive comparative claims.
|
|
||||||
- Prefer clear, action-oriented CTAs without heavy urgency.
|
|
||||||
|
|
||||||
## Brainstorming Defaults
|
|
||||||
|
|
||||||
- Favor breadth first when generating ideas.
|
|
||||||
- Generate three options by default before recommending one.
|
|
||||||
- Compare ideas primarily through user value, differentiation, and implementation realism.
|
|
||||||
- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost.
|
|
||||||
- Balance innovation with execution realism and require a believable path to implementation.
|
|
||||||
- Use a short-to-medium horizon with practical sequencing for roadmap framing.
|
|
||||||
- Turn brainstorming into a scoped implementation plan once a preferred option is selected.
|
|
||||||
- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing.
|
|
||||||
+13
-223
@@ -1,242 +1,32 @@
|
|||||||
# UI Stock Tracker — Project Documentation
|
# UI Stock Tracker — Design Notes & Development History
|
||||||
|
|
||||||
**Status:** ✅ Complete and running
|
Supplementary notes that go beyond the [README](./README.md): the reasoning behind the trickier parts of the scraper and the notable fixes made during development. For setup, architecture, API, and schema, see the README; for deployment see [UNRAID.md](./UNRAID.md).
|
||||||
**Last updated:** 2026-06-06
|
|
||||||
|
|
||||||
---
|
## Stock Detection Rationale
|
||||||
|
|
||||||
## Purpose
|
The scraper classifies each product page as `in_stock`, `sold_out`, or `unknown` using case- and whitespace-insensitive substring matching against the page's buttons. Two non-obvious details drove the matching rules:
|
||||||
|
|
||||||
Monitors product pages on [store.ui.com](https://store.ui.com/us/en) for stock availability and sends a Telegram alert the moment a watched item comes back in stock. Runs as a single persistent Docker container on Unraid with a clean web UI for managing tracked products.
|
**Auth-state difference.** The scraper runs logged out. On a sold-out item, Ubiquiti shows `"Login for Notifications"` to logged-out visitors instead of the logged-in `"Notify me when available"`. Both strings must be in the sold-out list, or logged-out checks would fall through to `unknown`.
|
||||||
|
|
||||||
---
|
**The `label` attribute exists only on the in-stock button.** The production DOM carries `label="Add to Cart"` on the primary Add-to-Cart button (confirmed in DevTools), but the sold-out "Login for Notifications" button has no `label` attribute. So in-stock has two redundant signals (the attribute *and* the button text) while sold-out relies on text alone — this asymmetry is by design, not an oversight.
|
||||||
|
|
||||||
## Stack
|
When neither signal matches, the scraper logs a `[Scraper] UNKNOWN debug` payload (page title, button labels, button texts) so a misclassification can be diagnosed from container logs without reproducing locally.
|
||||||
|
|
||||||
| Layer | Technology |
|
To avoid reading the page before React finishes rendering, the scraper waits 2.5s plus an active wait for a `<button>` to appear (up to 8s) before evaluating.
|
||||||
|---|---|
|
|
||||||
| Frontend | React 18 + TypeScript, Vite, Lucide icons |
|
|
||||||
| Backend | Node.js 20 + TypeScript, Express |
|
|
||||||
| Database | SQLite via `better-sqlite3` (WAL mode) |
|
|
||||||
| Scraper | Puppeteer-core + system Chromium |
|
|
||||||
| Alerts | Telegram Bot API (direct HTTP) |
|
|
||||||
| Container | Single Docker container — nginx + Node.js managed by supervisord |
|
|
||||||
| Web server | nginx — serves frontend, proxies `/api/` to Node.js on port 3001 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Container Architecture
|
|
||||||
|
|
||||||
One container runs three processes via **supervisord**:
|
|
||||||
|
|
||||||
```
|
|
||||||
supervisord
|
|
||||||
├── nginx → serves React build on :8080, proxies /api/ → localhost:3001
|
|
||||||
└── node → Express API, SQLite, Puppeteer scheduler, Telegram sender
|
|
||||||
```
|
|
||||||
|
|
||||||
The SQLite database is stored on a mounted volume at `/app/data/tracker.db` so it persists across rebuilds.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Features
|
|
||||||
|
|
||||||
### Stock Detection
|
|
||||||
Puppeteer navigates to each product URL, waits for React hydration (2.5s + active wait for `<button>` up to 8s), then evaluates with case- and whitespace-insensitive substring matching:
|
|
||||||
- Any `<button>` with `label="Add to Cart"` attribute, OR whose text contains `"add to cart"` → `in_stock`
|
|
||||||
- Any `<button>` whose text contains one of: `"login for notifications"`, `"login for updates"`, `"notify me when available"`, `"notify me"`, `"sold out"`, `"out of stock"`, `"currently unavailable"`, `"coming soon"` → `sold_out`
|
|
||||||
- Neither found → `unknown` (logs a `[Scraper] UNKNOWN debug` payload with page title, button labels, and button texts for diagnosis)
|
|
||||||
|
|
||||||
**Two gotchas the matcher handles:**
|
|
||||||
- **Auth-state difference.** The scraper runs logged out, so Ubiquiti shows `"Login for Notifications"` on sold-out items instead of the logged-in `"Notify me when available"`. Both must be in the sold-out list.
|
|
||||||
- **The `label` attribute exists only on the in-stock button.** Production DOM does carry `label="Add to Cart"` on the primary Add-to-Cart button (confirmed in DevTools), but the sold-out "Login for Notifications" button has no `label` attribute. So in-stock has two redundant signals (attribute + text), sold-out only has text — by design.
|
|
||||||
|
|
||||||
Product name is pulled from the `og:title` meta tag (with Ubiquiti store suffix stripped). Thumbnail is pulled from `og:image`.
|
|
||||||
|
|
||||||
### Alert Logic
|
|
||||||
- Alert fires **once** when an item transitions to `in_stock` and `alert_sent = 0`
|
|
||||||
- `alert_sent` is set to `1` after firing — no repeat alerts for the same in-stock event
|
|
||||||
- User clicks **Re-arm** in the UI to reset `alert_sent = 0`, enabling a new alert next time it comes back in stock
|
|
||||||
- This covers the "missed the buy window" scenario without spamming
|
|
||||||
|
|
||||||
### Scheduler
|
|
||||||
- Each watched item runs its own `setInterval` timer in memory
|
|
||||||
- Minimum interval enforced at **30 seconds** (backend + frontend)
|
|
||||||
- On startup, all active items are loaded from the DB and timers are started automatically
|
|
||||||
- Pause/Resume/Edit immediately updates the in-memory timer map and the DB
|
|
||||||
- A semaphore limits concurrent Puppeteer instances to **2** to prevent OOM on Unraid
|
|
||||||
|
|
||||||
### Frontend Polling
|
|
||||||
The UI polls `GET /api/items` every **10 seconds** to keep check counts and statuses current without requiring a page refresh.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Database Schema
|
|
||||||
|
|
||||||
```sql
|
|
||||||
watched_items (
|
|
||||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
||||||
url TEXT NOT NULL UNIQUE,
|
|
||||||
name TEXT, -- populated after first scrape
|
|
||||||
thumbnail_url TEXT, -- populated after first scrape
|
|
||||||
check_interval INTEGER NOT NULL DEFAULT 60, -- seconds, min 30
|
|
||||||
is_active INTEGER NOT NULL DEFAULT 1, -- 0 = paused
|
|
||||||
last_status TEXT NOT NULL DEFAULT 'unknown', -- in_stock | sold_out | unknown
|
|
||||||
alert_sent INTEGER NOT NULL DEFAULT 0, -- 1 = alert fired, awaiting re-arm
|
|
||||||
check_count INTEGER NOT NULL DEFAULT 0,
|
|
||||||
last_checked_at TEXT,
|
|
||||||
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
|
||||||
)
|
|
||||||
|
|
||||||
settings (
|
|
||||||
key TEXT PRIMARY KEY, -- telegram_bot_token | telegram_chat_id
|
|
||||||
value TEXT NOT NULL DEFAULT ''
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## API Endpoints
|
|
||||||
|
|
||||||
| Method | Path | Description |
|
|
||||||
|---|---|---|
|
|
||||||
| GET | `/api/items` | List all watched items |
|
|
||||||
| POST | `/api/items` | Add new item (url, check_interval) |
|
|
||||||
| PUT | `/api/items/:id` | Update interval or active state |
|
|
||||||
| DELETE | `/api/items/:id` | Remove item |
|
|
||||||
| POST | `/api/items/:id/pause` | Stop checking |
|
|
||||||
| POST | `/api/items/:id/resume` | Resume checking |
|
|
||||||
| POST | `/api/items/:id/reset` | Clear alert_sent (re-arm) |
|
|
||||||
| GET | `/api/settings` | Get Telegram credentials |
|
|
||||||
| PUT | `/api/settings` | Save Telegram credentials |
|
|
||||||
| POST | `/api/settings/test-telegram` | Send a test Telegram message |
|
|
||||||
| GET | `/api/health` | Health check |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Telegram Configuration
|
|
||||||
|
|
||||||
| Field | Value |
|
|
||||||
|---|---|
|
|
||||||
| Bot Token | `8769097441:AAFBqPlSTcTIi3I-F5ZIN9EEpwbNDzHg8hM` |
|
|
||||||
| Chat ID | `8435449432` |
|
|
||||||
|
|
||||||
Configured via **Settings** in the UI. Use **Test Alert** to verify the connection after saving.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Dockerfile Build Stages
|
|
||||||
|
|
||||||
```
|
|
||||||
Stage 1 — frontend-builder
|
|
||||||
node:20-slim → npm install → vite build → /build/frontend/dist
|
|
||||||
|
|
||||||
Stage 2 — backend-builder
|
|
||||||
node:20-slim + python3/make/g++ → npm install → tsc → npm prune --production
|
|
||||||
|
|
||||||
Stage 3 — runtime
|
|
||||||
node:20-slim + nginx + chromium + supervisor
|
|
||||||
├── Copies /build/frontend/dist → /usr/share/nginx/html
|
|
||||||
├── Copies /build/backend/dist → /app/backend/dist
|
|
||||||
├── Copies /build/backend/node_modules → /app/backend/node_modules
|
|
||||||
├── nginx.conf → /etc/nginx/conf.d/default.conf
|
|
||||||
└── supervisord.conf → /etc/supervisor/conf.d/supervisord.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## CI/CD — Gitea Actions
|
|
||||||
|
|
||||||
A workflow at `.gitea/workflows/docker-build.yml` automatically builds and pushes the Docker image on every push to `main`.
|
|
||||||
|
|
||||||
**What it does:**
|
|
||||||
1. Checks out the repo
|
|
||||||
2. Logs in to the private container registry at `registry.alwisp.com` using `gitea.REGISTRY_USER` + `secrets.REGISTRY_TOKEN`
|
|
||||||
3. Builds and pushes `registry.alwisp.com/{owner}/{repo}:latest`
|
|
||||||
|
|
||||||
**Runner:** `catthehacker/ubuntu:act-latest` (self-hosted compatible)
|
|
||||||
|
|
||||||
After a push triggers the build, pull the updated image on Unraid:
|
|
||||||
```bash
|
|
||||||
docker pull registry.alwisp.com/{owner}/{repo}:latest
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Build & Deploy
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Initial build and start
|
|
||||||
cd /mnt/user/appdata/ui-tracker
|
|
||||||
docker build -t ui-tracker .
|
|
||||||
# Then add container via Unraid Docker GUI — see UNRAID.md
|
|
||||||
|
|
||||||
# Rebuild after code changes
|
|
||||||
docker stop ui-tracker && docker rm ui-tracker
|
|
||||||
docker build -t ui-tracker .
|
|
||||||
# Re-add in Unraid GUI or: docker run ... (see UNRAID.md)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Fixes Applied During Development
|
## Fixes Applied During Development
|
||||||
|
|
||||||
### 1. `npm ci` → `npm install` (Dockerfile)
|
### 1. `npm ci` → `npm install` (Dockerfile)
|
||||||
`npm ci` requires a `package-lock.json` to exist. Since lockfiles were not committed, the build failed immediately. Switched both frontend and backend build stages to `npm install`.
|
`npm ci` requires a committed `package-lock.json`. Lockfiles were never committed, so the build failed immediately. Both the frontend and backend build stages use `npm install` instead. (This is why no lockfiles are present in the repo.)
|
||||||
|
|
||||||
### 2. TypeScript DOM lib missing (backend)
|
### 2. TypeScript DOM lib missing (backend)
|
||||||
`scraper.ts` uses `page.evaluate()` which runs a callback in the browser context. TypeScript flagged `document`, `navigator`, and `HTMLMetaElement` as unknown because the backend `tsconfig.json` only included `"lib": ["ES2020"]`. Fixed by adding `"DOM"` and `"DOM.Iterable"`:
|
`scraper.ts` uses `page.evaluate()`, whose callback runs in the browser context. TypeScript flagged `document`, `navigator`, and `HTMLMetaElement` as unknown because the backend `tsconfig.json` only included `"lib": ["ES2020"]`. Fixed by adding the DOM libs:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
"lib": ["ES2020", "DOM", "DOM.Iterable"]
|
"lib": ["ES2020", "DOM", "DOM.Iterable"]
|
||||||
```
|
```
|
||||||
|
|
||||||
`DOM.Iterable` was specifically required to allow `for...of` iteration over `NodeListOf<HTMLSpanElement>`.
|
`DOM.Iterable` was specifically required to allow `for...of` iteration over `NodeListOf<HTMLSpanElement>`.
|
||||||
|
|
||||||
### 3. Two containers → one container
|
### 3. Two containers → one container
|
||||||
Original design used separate `frontend` and `backend` Docker services in docker-compose. Consolidated into a single container using **supervisord** to run nginx and Node.js side by side, with nginx proxying `/api/` to `localhost:3001`. Removed `backend/Dockerfile`, `frontend/Dockerfile`, and `frontend/nginx.conf`. Root-level `Dockerfile`, `nginx.conf`, and `supervisord.conf` replaced them.
|
The original design used separate `frontend` and `backend` Docker services in docker-compose. These were consolidated into a single container running nginx and Node side by side under **supervisord**, with nginx proxying `/api/` to `localhost:3001`. Removed `backend/Dockerfile`, `frontend/Dockerfile`, and `frontend/nginx.conf`; the root-level `Dockerfile`, `nginx.conf`, and `supervisord.conf` replaced them.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
ui-tracker/
|
|
||||||
├── .gitea/
|
|
||||||
│ └── workflows/
|
|
||||||
│ └── docker-build.yml # Build + push to registry.alwisp.com on push to main
|
|
||||||
├── Dockerfile # 3-stage single-container build
|
|
||||||
├── docker-compose.yml # Single service, port 8080, ./data volume
|
|
||||||
├── nginx.conf # Serves frontend, proxies /api/ to Node
|
|
||||||
├── supervisord.conf # Keeps nginx + node alive
|
|
||||||
├── PROJECT.md # This file
|
|
||||||
├── UNRAID.md # Installation guide
|
|
||||||
├── data/ # SQLite DB lives here (volume mount)
|
|
||||||
├── backend/
|
|
||||||
│ ├── package.json
|
|
||||||
│ ├── tsconfig.json
|
|
||||||
│ └── src/
|
|
||||||
│ ├── index.ts # Express entry + scheduler init
|
|
||||||
│ ├── database.ts # Schema, getDb(), WatchedItem type
|
|
||||||
│ ├── scraper.ts # Puppeteer stock check + semaphore
|
|
||||||
│ ├── scheduler.ts # Per-item interval timers + alert logic
|
|
||||||
│ ├── telegram.ts # Bot API HTTP calls
|
|
||||||
│ └── routes/
|
|
||||||
│ ├── items.ts # Item CRUD + pause/resume/reset
|
|
||||||
│ └── settings.ts # Telegram config + test endpoint
|
|
||||||
└── frontend/
|
|
||||||
├── package.json
|
|
||||||
├── tsconfig.json
|
|
||||||
├── tsconfig.node.json
|
|
||||||
├── vite.config.ts
|
|
||||||
├── index.html
|
|
||||||
└── src/
|
|
||||||
├── main.tsx
|
|
||||||
├── App.tsx # Root, 10s polling, connection indicator
|
|
||||||
├── index.css # Dark theme, CSS variables, responsive grid
|
|
||||||
├── types/index.ts
|
|
||||||
├── api/client.ts # Typed fetch wrappers
|
|
||||||
└── components/
|
|
||||||
├── ItemCard.tsx # Thumbnail, badges, Re-arm, actions
|
|
||||||
├── AddItemModal.tsx
|
|
||||||
├── EditItemModal.tsx
|
|
||||||
└── SettingsModal.tsx # Token + chat ID + test alert
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -1,47 +1,173 @@
|
|||||||
# Drop-In Agent Instruction Suite
|
# UI Stock Tracker
|
||||||
|
|
||||||
This repository is a portable markdown instruction pack for coding agents.
|
Monitors product pages on [store.ui.com](https://store.ui.com/us/en) for stock availability and fires a Telegram alert the moment a watched item comes back in stock. Runs as a single self-contained Docker container on Unraid with a web UI for managing tracked products.
|
||||||
|
|
||||||
Copy these files into another repository to give the agent:
|
**Status:** Complete and running.
|
||||||
- a root `AGENTS.md` entrypoint,
|
|
||||||
- a central skill index,
|
|
||||||
- category hubs for routing,
|
|
||||||
- specialized skill files for common software, docs, UX, marketing, and ideation tasks.
|
|
||||||
|
|
||||||
## Structure
|
## How It Works
|
||||||
|
|
||||||
- `AGENTS.md` - base instructions and routing rules
|
A Puppeteer scraper visits each watched product URL on a per-item timer, waits for the React page to hydrate, and classifies the page as `in_stock`, `sold_out`, or `unknown` by inspecting the Add-to-Cart / notify buttons. When an item transitions to `in_stock`, the backend sends a one-time Telegram alert. You re-arm the item in the UI to enable the next alert, so you get notified without being spammed.
|
||||||
- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults
|
|
||||||
- `INSTALL.md` - copy and customization guide for other repositories
|
|
||||||
- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults
|
|
||||||
- `SKILLS.md` - canonical skill index
|
|
||||||
- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples
|
|
||||||
- `hubs/` - category-level routing guides
|
|
||||||
- `skills/` - specialized reusable skill files
|
|
||||||
|
|
||||||
## Design Goals
|
Stock detection rules:
|
||||||
|
|
||||||
- Plain markdown only
|
- A `<button>` with `label="Add to Cart"`, or whose text contains `"add to cart"` → `in_stock`.
|
||||||
- Cross-agent portability
|
- A `<button>` whose text contains `"login for notifications"`, `"login for updates"`, `"notify me when available"`, `"notify me"`, `"sold out"`, `"out of stock"`, `"currently unavailable"`, or `"coming soon"` → `sold_out`.
|
||||||
- Implementation-first defaults
|
- Neither found → `unknown` (logs a debug payload with page title and button texts).
|
||||||
- On-demand skill loading instead of loading everything every session
|
|
||||||
- Context-efficient routing for large skill libraries
|
|
||||||
- Prefilled deployment defaults without per-install questioning
|
|
||||||
- Repo-local instructions take precedence over this bundle
|
|
||||||
|
|
||||||
## Intended Workflow
|
The scraper runs logged out, so Ubiquiti shows `"Login for Notifications"` on sold-out items — that string is in the sold-out list by design. Product name comes from the `og:title` meta tag (store suffix stripped) and the thumbnail from `og:image`.
|
||||||
|
|
||||||
1. The agent reads `AGENTS.md`.
|
## Stack
|
||||||
2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in.
|
|
||||||
3. The agent checks `SKILLS.md`.
|
|
||||||
4. The agent opens only the relevant hub and skill files for the task.
|
|
||||||
5. The agent combines multiple skills when the task spans several domains.
|
|
||||||
|
|
||||||
## Core Categories
|
| Layer | Technology |
|
||||||
|
|---|---|
|
||||||
|
| Frontend | React 18 + TypeScript, Vite, Lucide icons |
|
||||||
|
| Backend | Node.js 20 + TypeScript, Express |
|
||||||
|
| Database | SQLite via `better-sqlite3` (WAL mode) |
|
||||||
|
| Scraper | `puppeteer-core` + system Chromium |
|
||||||
|
| Alerts | Telegram Bot API (direct HTTP) |
|
||||||
|
| Container | Single Docker image — nginx + Node managed by supervisord |
|
||||||
|
|
||||||
- Software development
|
## Architecture
|
||||||
- Debugging
|
|
||||||
- Documentation
|
One container runs two processes under **supervisord**:
|
||||||
- UI/UX
|
|
||||||
- Marketing
|
```
|
||||||
- Brainstorming
|
supervisord
|
||||||
|
├── nginx → serves the React build on :8080, proxies /api/ → 127.0.0.1:3001
|
||||||
|
└── node → Express API, SQLite, Puppeteer scheduler, Telegram sender (:3001)
|
||||||
|
```
|
||||||
|
|
||||||
|
The SQLite database lives on a mounted volume at `/app/data/tracker.db`, so it persists across rebuilds.
|
||||||
|
|
||||||
|
Backend runtime behavior:
|
||||||
|
|
||||||
|
- **Scheduler** — each active item runs its own in-memory `setInterval`; timers start automatically on boot from the DB. Minimum interval is **30 seconds** (enforced backend and frontend). Pause / Resume / Edit update both the timer map and the DB immediately.
|
||||||
|
- **Concurrency** — a semaphore caps concurrent Puppeteer instances at **2** to avoid OOM on Unraid.
|
||||||
|
- **Alert logic** — an alert fires once when an item goes `in_stock` with `alert_sent = 0`, then sets `alert_sent = 1`. **Re-arm** in the UI resets it to `0`.
|
||||||
|
- **Frontend polling** — the UI polls `GET /api/items` every **10 seconds**.
|
||||||
|
|
||||||
|
## Repository Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
ui-tracker/
|
||||||
|
├── Dockerfile # 3-stage single-container build
|
||||||
|
├── docker-compose.yml # Single service, port 8080, ./data volume
|
||||||
|
├── nginx.conf # Serves frontend, proxies /api/ to Node
|
||||||
|
├── supervisord.conf # Keeps nginx + node alive
|
||||||
|
├── .gitea/workflows/ # CI: build + push image on push to main
|
||||||
|
├── data/ # SQLite DB (volume mount)
|
||||||
|
├── backend/
|
||||||
|
│ └── src/
|
||||||
|
│ ├── index.ts # Express entry + scheduler init
|
||||||
|
│ ├── database.ts # Schema, getDb(), WatchedItem type
|
||||||
|
│ ├── scraper.ts # Puppeteer stock check + semaphore
|
||||||
|
│ ├── scheduler.ts # Per-item timers + alert logic
|
||||||
|
│ ├── telegram.ts # Bot API HTTP calls
|
||||||
|
│ └── routes/ # items.ts, settings.ts
|
||||||
|
└── frontend/
|
||||||
|
└── src/
|
||||||
|
├── App.tsx # Root, 10s polling, connection indicator
|
||||||
|
├── api/client.ts # Typed fetch wrappers
|
||||||
|
├── types/index.ts
|
||||||
|
└── components/ # ItemCard, AddItemModal, EditItemModal, SettingsModal
|
||||||
|
```
|
||||||
|
|
||||||
|
## API
|
||||||
|
|
||||||
|
| Method | Path | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| GET | `/api/items` | List all watched items |
|
||||||
|
| POST | `/api/items` | Add new item (`url`, `check_interval`) |
|
||||||
|
| PUT | `/api/items/:id` | Update interval or active state |
|
||||||
|
| DELETE | `/api/items/:id` | Remove item |
|
||||||
|
| POST | `/api/items/:id/pause` | Stop checking |
|
||||||
|
| POST | `/api/items/:id/resume` | Resume checking |
|
||||||
|
| POST | `/api/items/:id/reset` | Clear `alert_sent` (re-arm) |
|
||||||
|
| GET | `/api/settings` | Get Telegram credentials |
|
||||||
|
| PUT | `/api/settings` | Save Telegram credentials |
|
||||||
|
| POST | `/api/settings/test-telegram` | Send a test Telegram message |
|
||||||
|
| GET | `/api/health` | Health check |
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
watched_items (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
url TEXT NOT NULL UNIQUE,
|
||||||
|
name TEXT, -- populated after first scrape
|
||||||
|
thumbnail_url TEXT, -- populated after first scrape
|
||||||
|
check_interval INTEGER NOT NULL DEFAULT 60, -- seconds, min 30
|
||||||
|
is_active INTEGER NOT NULL DEFAULT 1, -- 0 = paused
|
||||||
|
last_status TEXT NOT NULL DEFAULT 'unknown', -- in_stock | sold_out | unknown
|
||||||
|
alert_sent INTEGER NOT NULL DEFAULT 0, -- 1 = alert fired, awaiting re-arm
|
||||||
|
check_count INTEGER NOT NULL DEFAULT 0,
|
||||||
|
last_checked_at TEXT,
|
||||||
|
created_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||||
|
)
|
||||||
|
|
||||||
|
settings (
|
||||||
|
key TEXT PRIMARY KEY, -- telegram_bot_token | telegram_chat_id
|
||||||
|
value TEXT NOT NULL DEFAULT ''
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Local Development
|
||||||
|
|
||||||
|
The backend and frontend run independently in dev.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Backend (http://localhost:3001)
|
||||||
|
cd backend
|
||||||
|
npm install
|
||||||
|
npm run dev # ts-node-dev, respawns on change
|
||||||
|
|
||||||
|
# Frontend (http://localhost:5173, Vite)
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Backend env vars (set automatically in the container via `supervisord.conf`): `PORT` (default `3001`), `DATABASE_PATH` (default `/app/data/tracker.db`), `PUPPETEER_EXECUTABLE_PATH` (default `/usr/bin/chromium`).
|
||||||
|
|
||||||
|
> Lockfiles are not committed, so the Docker build uses `npm install` rather than `npm ci`.
|
||||||
|
|
||||||
|
## Build & Run (Docker)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t ui-tracker .
|
||||||
|
docker compose up -d # serves on http://localhost:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
The image builds in three stages: Vite builds the frontend, `tsc` compiles the backend (then `npm prune --production`), and the runtime stage assembles `node:20-slim` + nginx + Chromium + supervisor.
|
||||||
|
|
||||||
|
Full Unraid install instructions are in [UNRAID.md](./UNRAID.md).
|
||||||
|
|
||||||
|
## CI/CD
|
||||||
|
|
||||||
|
`.gitea/workflows/docker-build.yml` builds and pushes the image on every push to `main`:
|
||||||
|
|
||||||
|
1. Checks out the repo.
|
||||||
|
2. Logs in to the private registry at `registry.alwisp.com` (`secrets.REGISTRY_USER` / `secrets.REGISTRY_TOKEN`).
|
||||||
|
3. Builds and pushes `registry.alwisp.com/{owner}/{repo}:latest`.
|
||||||
|
|
||||||
|
Pull the updated image on Unraid afterward:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker pull registry.alwisp.com/{owner}/{repo}:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
## Telegram Configuration
|
||||||
|
|
||||||
|
Configure via **Settings** in the UI, then use **Test Alert** to verify.
|
||||||
|
|
||||||
|
| Field | Value |
|
||||||
|
|---|---|
|
||||||
|
| Bot Token | `8769097441:AAFBqPlSTcTIi3I-F5ZIN9EEpwbNDzHg8hM` |
|
||||||
|
| Chat ID | `8435449432` |
|
||||||
|
|
||||||
|
> ⚠️ These are live credentials committed to the repo. Rotate the bot token (via @BotFather) if this repository is ever made public or shared.
|
||||||
|
|
||||||
|
## Further Docs
|
||||||
|
|
||||||
|
- [PROJECT.md](./PROJECT.md) — deeper design notes and development history.
|
||||||
|
- [UNRAID.md](./UNRAID.md) — step-by-step Unraid install and troubleshooting.
|
||||||
|
|||||||
@@ -1,84 +0,0 @@
|
|||||||
# Routing Examples
|
|
||||||
|
|
||||||
Use these examples to validate that the suite routes clearly from `AGENTS.md` to the right hub files and specialized skills.
|
|
||||||
|
|
||||||
In deployments with a filled-in [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md), the agent should read that file after `AGENTS.md` and before opening hubs or skills.
|
|
||||||
|
|
||||||
## Representative Prompts
|
|
||||||
|
|
||||||
### Fix a failing backend test and explain the root cause
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Debugging Hub](./hubs/debugging.md)
|
|
||||||
- Use [Bug Triage](./skills/debugging/bug-triage.md)
|
|
||||||
- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
|
|
||||||
- Add [API and Backend Work](./skills/software/api-backend.md)
|
|
||||||
- Add [Test Strategy](./skills/software/test-strategy.md)
|
|
||||||
|
|
||||||
### Build a new UI settings page with good UX and copy
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Software Development Hub](./hubs/software-development.md)
|
|
||||||
- Use [Feature Implementation](./skills/software/feature-implementation.md)
|
|
||||||
- Use [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
|
|
||||||
- Add [UI/UX Hub](./hubs/ui-ux.md)
|
|
||||||
- Use [UX Review](./skills/ui-ux/ux-review.md)
|
|
||||||
- Add [Product Copy](./skills/marketing/product-copy.md)
|
|
||||||
|
|
||||||
### Write release notes and update onboarding docs for this feature
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Documentation Hub](./hubs/documentation.md)
|
|
||||||
- Use [Release and Change Summary](./skills/software/release-change-summary.md)
|
|
||||||
- Use [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
|
|
||||||
- Add [Technical Documentation](./skills/documentation/technical-docs.md) if setup or behavior changed
|
|
||||||
|
|
||||||
### Brainstorm three product directions and turn the best one into a scoped implementation plan
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Brainstorming Hub](./hubs/brainstorming.md)
|
|
||||||
- Use [Ideation](./skills/brainstorming/ideation.md)
|
|
||||||
- Use [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
|
|
||||||
- Add [Repository Exploration](./skills/software/repo-exploration.md) if the plan must align to an existing codebase
|
|
||||||
- Add [Feature Implementation](./skills/software/feature-implementation.md) for implementation-ready shaping
|
|
||||||
|
|
||||||
### Review this PR for bugs, regressions, and missing tests
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Software Development Hub](./hubs/software-development.md)
|
|
||||||
- Use [Code Review](./skills/software/code-review.md)
|
|
||||||
- Add [Test Strategy](./skills/software/test-strategy.md)
|
|
||||||
|
|
||||||
### Draft launch messaging for a developer tool feature
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Marketing Hub](./hubs/marketing.md)
|
|
||||||
- Use [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
|
|
||||||
- Use [Marketing Content](./skills/marketing/marketing-content.md)
|
|
||||||
- Add [Technical Documentation](./skills/documentation/technical-docs.md) if claims need implementation-grounded detail
|
|
||||||
|
|
||||||
### Plan a risky framework upgrade without derailing feature delivery
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Software Development Hub](./hubs/software-development.md)
|
|
||||||
- Use [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
|
|
||||||
- Add [Test Strategy](./skills/software/test-strategy.md)
|
|
||||||
- Add [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
|
|
||||||
- Add [Release and Change Summary](./skills/software/release-change-summary.md) if rollout communication matters
|
|
||||||
|
|
||||||
### Respond to a live production issue and leave the system easier to diagnose next time
|
|
||||||
|
|
||||||
- Start at [AGENTS.md](./AGENTS.md)
|
|
||||||
- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
|
|
||||||
- Open [Debugging Hub](./hubs/debugging.md)
|
|
||||||
- Use [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
|
|
||||||
- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
|
|
||||||
- Add [Observability and Operability](./skills/software/observability-operability.md)
|
|
||||||
- Add [Bug Triage](./skills/debugging/bug-triage.md) if reproduction or impact framing is still loose
|
|
||||||
@@ -1,91 +0,0 @@
|
|||||||
# Skill Index
|
|
||||||
|
|
||||||
This file is the canonical registry for the instruction suite. Read this index after `AGENTS.md` and the deployment profile, then open only the hub and skill files needed for the current task.
|
|
||||||
|
|
||||||
## Skill Contract
|
|
||||||
|
|
||||||
Every skill file follows the same structure:
|
|
||||||
- `Purpose`
|
|
||||||
- `When to use`
|
|
||||||
- `Inputs to gather`
|
|
||||||
- `How to work`
|
|
||||||
- `Output expectations`
|
|
||||||
- `Quality checklist`
|
|
||||||
- `Handoff notes`
|
|
||||||
|
|
||||||
## Loading Guidance
|
|
||||||
|
|
||||||
- If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) is filled in, treat it as the default preference layer before applying generic skill guidance.
|
|
||||||
- Start narrow: one hub plus the smallest set of specialized skills that covers the task.
|
|
||||||
- Typical task size: two to four skills.
|
|
||||||
- Larger, cross-functional tasks may need four to six skills, but only when each one adds a distinct concern.
|
|
||||||
- Prefer high-leverage skills that shape implementation quality over collecting adjacent but redundant guidance.
|
|
||||||
- When in doubt, prioritize repository exploration, implementation/debugging, testing, and one domain-specific skill.
|
|
||||||
|
|
||||||
## Category Hubs
|
|
||||||
|
|
||||||
- [Software Development](./hubs/software-development.md)
|
|
||||||
- [Debugging](./hubs/debugging.md)
|
|
||||||
- [Documentation](./hubs/documentation.md)
|
|
||||||
- [UI/UX](./hubs/ui-ux.md)
|
|
||||||
- [Marketing](./hubs/marketing.md)
|
|
||||||
- [Brainstorming](./hubs/brainstorming.md)
|
|
||||||
|
|
||||||
## Specialized Skills
|
|
||||||
|
|
||||||
### Software Development
|
|
||||||
|
|
||||||
- [Architecture and System Design](./skills/software/architecture-system-design.md)
|
|
||||||
- [Feature Implementation](./skills/software/feature-implementation.md)
|
|
||||||
- [Refactoring](./skills/software/refactoring.md)
|
|
||||||
- [Code Review](./skills/software/code-review.md)
|
|
||||||
- [Test Strategy](./skills/software/test-strategy.md)
|
|
||||||
- [API and Backend Work](./skills/software/api-backend.md)
|
|
||||||
- [Database Migrations and Data Evolution](./skills/software/database-migrations.md)
|
|
||||||
- [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
|
|
||||||
- [Performance Optimization](./skills/software/performance-optimization.md)
|
|
||||||
- [Security Review and Hardening](./skills/software/security-review-hardening.md)
|
|
||||||
- [Observability and Operability](./skills/software/observability-operability.md)
|
|
||||||
- [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
|
|
||||||
- [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
|
|
||||||
- [Repository Exploration](./skills/software/repo-exploration.md)
|
|
||||||
- [Release and Change Summary](./skills/software/release-change-summary.md)
|
|
||||||
|
|
||||||
### Debugging
|
|
||||||
|
|
||||||
- [Bug Triage](./skills/debugging/bug-triage.md)
|
|
||||||
- [Debugging Workflow](./skills/debugging/debugging-workflow.md)
|
|
||||||
- [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
|
|
||||||
- [Architecture Decision Records](./skills/documentation/architecture-decision-records.md)
|
|
||||||
- [Technical Documentation](./skills/documentation/technical-docs.md)
|
|
||||||
- [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
|
|
||||||
|
|
||||||
### UI/UX
|
|
||||||
|
|
||||||
- [UX Review](./skills/ui-ux/ux-review.md)
|
|
||||||
- [Accessibility Review](./skills/ui-ux/accessibility-review.md)
|
|
||||||
- [Design System and UI Consistency](./skills/ui-ux/design-system-consistency.md)
|
|
||||||
|
|
||||||
### Marketing
|
|
||||||
|
|
||||||
- [Product Copy](./skills/marketing/product-copy.md)
|
|
||||||
- [Marketing Content](./skills/marketing/marketing-content.md)
|
|
||||||
- [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
|
|
||||||
- [Content Strategy and SEO](./skills/marketing/content-strategy-seo.md)
|
|
||||||
|
|
||||||
### Brainstorming
|
|
||||||
|
|
||||||
- [Ideation](./skills/brainstorming/ideation.md)
|
|
||||||
- [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
|
|
||||||
- [Roadmap and Opportunity Prioritization](./skills/brainstorming/roadmap-opportunity-prioritization.md)
|
|
||||||
|
|
||||||
## Quick Routing Hints
|
|
||||||
|
|
||||||
- If the task changes code, start with the software development hub.
|
|
||||||
- If the task starts from a defect, regression, failing test, or unclear breakage, add debugging skills.
|
|
||||||
- If the task changes how people use, adopt, or understand the product, add documentation and possibly UX or marketing skills.
|
|
||||||
- If the task asks for options, concepts, or strategic directions before execution, use brainstorming skills.
|
|
||||||
- If the task affects long-term system health, look for architecture, security, performance, observability, dependency, or maintenance skills before loading more tactical ones.
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
# Brainstorming Hub
|
|
||||||
|
|
||||||
Use this hub when the task is to generate options, explore solution space, compare directions, or turn rough ideas into structured next steps.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains brainstorming defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- The user wants concepts, options, or strategic directions
|
|
||||||
- Requirements are early-stage and need shaping
|
|
||||||
- A promising idea needs to become a scoped plan
|
|
||||||
- The team wants alternatives before implementation
|
|
||||||
|
|
||||||
## Skill Routing
|
|
||||||
|
|
||||||
- [Ideation](../skills/brainstorming/ideation.md) for broad option generation and concept creation
|
|
||||||
- [Structured Brainstorming](../skills/brainstorming/structured-brainstorming.md) for narrowing, comparing, scoring, and turning ideas into action
|
|
||||||
- [Roadmap and Opportunity Prioritization](../skills/brainstorming/roadmap-opportunity-prioritization.md) for sequencing initiatives, balancing impact versus effort, and choosing what should happen next
|
|
||||||
|
|
||||||
## Common Combinations
|
|
||||||
|
|
||||||
- Product concepting: ideation + messaging/positioning
|
|
||||||
- Solution design: ideation + structured brainstorming + repository exploration
|
|
||||||
- From ideas to build plan: structured brainstorming + feature implementation + test strategy
|
|
||||||
- Long-range planning: roadmap and opportunity prioritization + maintenance and technical debt planning + architecture and system design
|
|
||||||
@@ -1,27 +0,0 @@
|
|||||||
# Debugging Hub
|
|
||||||
|
|
||||||
Use this hub for work that begins with a defect, regression, failing test, production issue, or confusing system behavior.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains debugging defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- A test is failing and the cause is unclear
|
|
||||||
- A user-reported bug needs reproduction and triage
|
|
||||||
- The system behaves inconsistently across environments or inputs
|
|
||||||
- A suspected regression needs careful isolation
|
|
||||||
|
|
||||||
## Start With
|
|
||||||
|
|
||||||
- [Bug Triage](../skills/debugging/bug-triage.md) to define the problem, impact, environment, and reproduction path
|
|
||||||
- [Debugging Workflow](../skills/debugging/debugging-workflow.md) to isolate root cause and verify a fix
|
|
||||||
|
|
||||||
## Combine With
|
|
||||||
|
|
||||||
- [API and Backend Work](../skills/software/api-backend.md) when the issue is server-side or data-related
|
|
||||||
- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) when the issue is client-side or interaction-related
|
|
||||||
- [Test Strategy](../skills/software/test-strategy.md) when the fix needs coverage
|
|
||||||
- [Release and Change Summary](../skills/software/release-change-summary.md) when the resolution should be communicated clearly
|
|
||||||
- [Incident Response and Stabilization](../skills/debugging/incident-response-stabilization.md) when the issue is live, user-impacting, or needs temporary containment before a full fix
|
|
||||||
- [Observability and Operability](../skills/software/observability-operability.md) when logs, metrics, traces, or alerting gaps block diagnosis
|
|
||||||
- [Performance Optimization](../skills/software/performance-optimization.md) when the problem is latency, throughput, memory, or rendering related
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
# Documentation Hub
|
|
||||||
|
|
||||||
Use this hub when the task changes how people understand, adopt, operate, or maintain the product.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains documentation defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- Write or update technical documentation
|
|
||||||
- Improve onboarding or contributor guidance
|
|
||||||
- Create release notes or change summaries
|
|
||||||
- Align docs with code or product changes
|
|
||||||
|
|
||||||
## Skill Routing
|
|
||||||
|
|
||||||
- [Architecture Decision Records](../skills/documentation/architecture-decision-records.md) for capturing meaningful technical choices, tradeoffs, and why a direction was selected
|
|
||||||
- [Technical Documentation](../skills/documentation/technical-docs.md) for architecture, APIs, workflows, operational guidance, and usage docs
|
|
||||||
- [Onboarding Documentation](../skills/documentation/onboarding-docs.md) for setup guides, contributor onboarding, first-run experience, and internal enablement
|
|
||||||
- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, changelog writing, and rollout explanations
|
|
||||||
|
|
||||||
## Common Combinations
|
|
||||||
|
|
||||||
- New feature: technical docs + release/change summary
|
|
||||||
- Developer experience improvement: onboarding docs + technical docs
|
|
||||||
- Product launch: release/change summary + messaging/positioning + marketing content
|
|
||||||
- Long-lived architecture change: architecture and system design + architecture decision records + technical docs
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
# Marketing Hub
|
|
||||||
|
|
||||||
Use this hub for external-facing product language, launch assets, positioning, and persuasive communication.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains marketing defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- Draft launch messaging or feature announcements
|
|
||||||
- Improve website or product marketing copy
|
|
||||||
- Clarify product differentiation and audience fit
|
|
||||||
- Create marketing assets tied to engineering or product changes
|
|
||||||
|
|
||||||
## Skill Routing
|
|
||||||
|
|
||||||
- [Product Copy](../skills/marketing/product-copy.md) for UI-adjacent language, concise product text, and conversion-oriented wording
|
|
||||||
- [Marketing Content](../skills/marketing/marketing-content.md) for launch posts, feature pages, emails, social copy, and content drafts
|
|
||||||
- [Messaging and Positioning](../skills/marketing/messaging-positioning.md) for audience, value proposition, differentiation, and narrative framing
|
|
||||||
- [Content Strategy and SEO](../skills/marketing/content-strategy-seo.md) for durable organic content, search intent alignment, and content planning
|
|
||||||
|
|
||||||
## Common Combinations
|
|
||||||
|
|
||||||
- Feature launch: messaging/positioning + marketing content + release/change summary
|
|
||||||
- Landing page refresh: product copy + messaging/positioning + UX review
|
|
||||||
- Developer tool announcement: marketing content + technical docs + messaging/positioning
|
|
||||||
- Evergreen growth work: content strategy and SEO + messaging/positioning + technical docs
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
# Software Development Hub
|
|
||||||
|
|
||||||
Use this hub for implementation-focused software work: features, refactors, code review, tests, backend changes, frontend changes, and release communication tied to engineering output.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains software defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- Build or modify product functionality
|
|
||||||
- Improve maintainability or architecture
|
|
||||||
- Review existing code for bugs, regressions, or missing tests
|
|
||||||
- Plan or add verification coverage
|
|
||||||
- Explore an unfamiliar codebase before changing it
|
|
||||||
|
|
||||||
## Start With
|
|
||||||
|
|
||||||
- [Repository Exploration](../skills/software/repo-exploration.md) for unfamiliar codebases or vague requests
|
|
||||||
- [Feature Implementation](../skills/software/feature-implementation.md) for net-new behavior or substantial changes
|
|
||||||
|
|
||||||
## Skill Routing
|
|
||||||
|
|
||||||
- [Architecture and System Design](../skills/software/architecture-system-design.md) for major system changes, design tradeoffs, and long-lived technical direction
|
|
||||||
- [Refactoring](../skills/software/refactoring.md) for structure improvements without intended behavior changes
|
|
||||||
- [Code Review](../skills/software/code-review.md) for finding bugs, regressions, risky assumptions, and missing coverage
|
|
||||||
- [Test Strategy](../skills/software/test-strategy.md) for designing, expanding, or evaluating verification
|
|
||||||
- [API and Backend Work](../skills/software/api-backend.md) for services, storage, schema, integration, and server-side logic
|
|
||||||
- [Database Migrations and Data Evolution](../skills/software/database-migrations.md) for schema changes, backfills, compatibility windows, and rollout-safe data transitions
|
|
||||||
- [Dependency Lifecycle Management](../skills/software/dependency-lifecycle.md) for upgrades, dependency risk reduction, and ecosystem maintenance
|
|
||||||
- [Performance Optimization](../skills/software/performance-optimization.md) for latency, throughput, rendering, and resource-efficiency work
|
|
||||||
- [Security Review and Hardening](../skills/software/security-review-hardening.md) for auth, validation, secrets, exposure, and abuse resistance concerns
|
|
||||||
- [Observability and Operability](../skills/software/observability-operability.md) for logging, metrics, traces, alerts, and operational readiness
|
|
||||||
- [Maintenance and Technical Debt Planning](../skills/software/maintenance-technical-debt.md) for long-horizon cleanup, risk reduction, and sequencing work
|
|
||||||
- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for interfaces, interaction logic, and client-side UX execution
|
|
||||||
- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, summaries, migration notes, and rollout communication
|
|
||||||
|
|
||||||
## Common Combinations
|
|
||||||
|
|
||||||
- New feature: repository exploration + feature implementation + test strategy + technical docs
|
|
||||||
- Backend bug fix: bug triage + debugging workflow + API and backend work + release/change summary
|
|
||||||
- UI feature: feature implementation + frontend UI implementation + UX review + product copy
|
|
||||||
- PR review: code review + test strategy
|
|
||||||
- Platform change: architecture and system design + API/backend work + observability and operability + technical docs
|
|
||||||
- Risky upgrade: dependency lifecycle management + test strategy + release/change summary
|
|
||||||
- Data model change: architecture and system design + database migrations and data evolution + API/backend work
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
# UI/UX Hub
|
|
||||||
|
|
||||||
Use this hub when the task depends on interface quality, interaction flow, usability, clarity, or user-facing content design.
|
|
||||||
|
|
||||||
If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains UI/UX defaults, apply those preferences before falling back to the generic routing in this hub.
|
|
||||||
|
|
||||||
## When To Use
|
|
||||||
|
|
||||||
- Review a screen, flow, or feature for UX weaknesses
|
|
||||||
- Improve copy, hierarchy, clarity, or task completion
|
|
||||||
- Implement or revise UI behavior with usability in mind
|
|
||||||
|
|
||||||
## Skill Routing
|
|
||||||
|
|
||||||
- [UX Review](../skills/ui-ux/ux-review.md) for critique, heuristics, friction detection, and recommendations
|
|
||||||
- [Accessibility Review](../skills/ui-ux/accessibility-review.md) for inclusive interaction quality, keyboard support, semantics, contrast, and assistive-technology readiness
|
|
||||||
- [Design System and UI Consistency](../skills/ui-ux/design-system-consistency.md) for component reuse, visual consistency, and scalable UI patterns
|
|
||||||
- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for shipping the UI changes
|
|
||||||
- [Product Copy](../skills/marketing/product-copy.md) when labels, empty states, CTAs, or in-product messaging matter
|
|
||||||
|
|
||||||
## Common Combinations
|
|
||||||
|
|
||||||
- New settings page: frontend UI implementation + UX review + product copy
|
|
||||||
- Navigation cleanup: UX review + frontend UI implementation
|
|
||||||
- Conversion-focused UI change: UX review + product copy + messaging/positioning
|
|
||||||
- UI platform work: design system and UI consistency + frontend UI implementation + accessibility review
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Ideation
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Generate strong options quickly without locking too early onto the first plausible idea.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- The user wants multiple concepts, approaches, or product directions
|
|
||||||
- Requirements are early and the solution space is still wide
|
|
||||||
- A team needs creative alternatives before choosing a path
|
|
||||||
- You want to escape local maxima in product or technical thinking
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Goal, audience, constraints, and success criteria
|
|
||||||
- What is already known, tried, or ruled out
|
|
||||||
- Time, complexity, and implementation constraints
|
|
||||||
- The desired balance of novelty versus practicality
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Produce several meaningfully different options, not minor variations of one idea.
|
|
||||||
- Cover a range from safer to bolder approaches when useful.
|
|
||||||
- Make tradeoffs explicit so ideas are easy to compare.
|
|
||||||
- Keep ideas concrete enough that someone can imagine implementation or execution.
|
|
||||||
- Narrow only after the option space is genuinely explored.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Distinct options with concise descriptions
|
|
||||||
- Tradeoffs, strengths, and risks for each option
|
|
||||||
- A recommended direction when appropriate
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Options are genuinely different in mechanism or strategy.
|
|
||||||
- Ideas respect the stated constraints.
|
|
||||||
- Tradeoffs are visible rather than implied.
|
|
||||||
- Recommendations, if given, follow from the comparison.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note whether the ideas are exploratory, implementation-ready, or need structured narrowing next.
|
|
||||||
- Pair with structured brainstorming when the next step is selecting and shaping one path.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Roadmap and Opportunity Prioritization
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Choose what to do next by comparing opportunities, maintenance work, and strategic bets against explicit decision criteria.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Too many plausible initiatives compete for limited time
|
|
||||||
- Feature work and maintenance work need to be balanced
|
|
||||||
- A team needs a more defensible roadmap discussion
|
|
||||||
- Promising ideas need sequencing rather than more generation
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Candidate initiatives or workstreams
|
|
||||||
- Decision criteria such as impact, urgency, effort, risk reduction, or strategic fit
|
|
||||||
- Dependencies, timing constraints, and team capacity
|
|
||||||
- Evidence for expected payoff or avoided risk
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Make prioritization criteria explicit before ranking work.
|
|
||||||
- Compare user value, strategic value, and risk reduction together.
|
|
||||||
- Treat maintenance and enabling work as first-class opportunities when they materially improve future delivery.
|
|
||||||
- Distinguish what is urgent, what is high leverage, and what is merely attractive.
|
|
||||||
- Produce a sequence that a team can actually act on.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Prioritized list or roadmap recommendation
|
|
||||||
- Clear rationale for order and tradeoffs
|
|
||||||
- Notes on what to defer, revisit, or validate next
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Priorities reflect stated criteria rather than intuition alone.
|
|
||||||
- Sequencing respects dependencies and capacity.
|
|
||||||
- Lower-priority items are deferred for a reason, not forgotten accidentally.
|
|
||||||
- Maintenance work is evaluated on outcomes, not optics.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note what new evidence would most change the ranking.
|
|
||||||
- Pair with maintenance and technical debt planning or structured brainstorming when the decision needs deeper shaping.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Structured Brainstorming
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Turn rough ideas into decision-ready options by comparing them systematically, narrowing intelligently, and shaping the chosen direction into actionable next steps.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Many ideas exist and the team needs a clear recommendation
|
|
||||||
- A promising concept needs scoping before implementation
|
|
||||||
- Tradeoffs need to be surfaced explicitly
|
|
||||||
- The next step is choosing, sequencing, or planning rather than generating more ideas
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Candidate ideas or possible approaches
|
|
||||||
- Decision criteria such as impact, effort, risk, speed, or strategic fit
|
|
||||||
- Constraints on time, team, technical feasibility, or audience needs
|
|
||||||
- Any assumptions that materially change the choice
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Define the decision criteria before ranking options.
|
|
||||||
- Compare options on the criteria that actually matter for the request.
|
|
||||||
- Remove weak options quickly once the reason is clear.
|
|
||||||
- Turn the selected direction into a scoped set of next steps or a buildable outline.
|
|
||||||
- Keep the analysis proportional; do not over-formalize simple decisions.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear comparison of options
|
|
||||||
- Recommended direction with reasoning
|
|
||||||
- A scoped next-step plan or action outline
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Decision criteria are explicit and relevant.
|
|
||||||
- The recommendation follows from the comparison rather than preference alone.
|
|
||||||
- The chosen path is actionable, not just inspirational.
|
|
||||||
- Key assumptions are visible.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note what would most likely change the recommendation.
|
|
||||||
- Pair with feature implementation, repo exploration, or messaging skills when moving from choice to execution.
|
|
||||||
@@ -1,46 +0,0 @@
|
|||||||
# Bug Triage
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Frame a defect clearly before or during debugging so the team understands impact, reproduction, suspected scope, and next actions.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- A bug report arrives with incomplete detail
|
|
||||||
- A failing test or regression needs initial framing
|
|
||||||
- Multiple issues compete for attention and severity matters
|
|
||||||
- You need a reliable reproduction path before deeper debugging
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Reported symptoms, expected behavior, and actual behavior
|
|
||||||
- Reproduction steps, environment, and frequency
|
|
||||||
- User impact, severity, and likely affected surfaces
|
|
||||||
- Recent changes, logs, or tests that may be related
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Turn vague symptoms into a concrete problem statement.
|
|
||||||
- Reproduce the issue when possible and tighten the reproduction steps.
|
|
||||||
- Separate confirmed facts from assumptions.
|
|
||||||
- Estimate impact and likely blast radius before diving into fixes.
|
|
||||||
- Identify the next best debugging step if root cause is not yet known.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear bug statement and reproduction status
|
|
||||||
- Impact and severity assessment
|
|
||||||
- Suspected scope or likely component area
|
|
||||||
- Recommended next debugging or fix step
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The issue is described in observable terms rather than guesses.
|
|
||||||
- Reproduction details are specific enough to be reused.
|
|
||||||
- Impact is clear enough to prioritize intelligently.
|
|
||||||
- Unknowns are named instead of hidden.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Record environment details and whether the issue is deterministic, intermittent, or unconfirmed.
|
|
||||||
- Pair with debugging workflow once the problem is framed well enough to investigate deeply.
|
|
||||||
@@ -1,46 +0,0 @@
|
|||||||
# Debugging Workflow
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- The defect is real but the cause is unclear
|
|
||||||
- A failing test needs investigation
|
|
||||||
- The system has inconsistent or environment-specific behavior
|
|
||||||
- A regression may have multiple plausible causes
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Reproduction path or failing signal
|
|
||||||
- Relevant code paths, logs, traces, state transitions, and recent changes
|
|
||||||
- Existing tests or ways to validate a hypothesis
|
|
||||||
- Environment details that may influence behavior
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
|
|
||||||
- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
|
|
||||||
- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
|
|
||||||
- Fix the root cause rather than only masking symptoms when feasible.
|
|
||||||
- Re-run the original failing signal and add regression protection if appropriate.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Root cause explanation tied to evidence
|
|
||||||
- Fix or recommended fix approach
|
|
||||||
- Verification that the original issue is resolved
|
|
||||||
- Remaining uncertainty, if any
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The explanation connects cause to symptom clearly.
|
|
||||||
- The chosen fix addresses the real failure mechanism.
|
|
||||||
- Verification includes the original failing path.
|
|
||||||
- Regression protection is considered when the bug is likely to recur.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
|
|
||||||
- Mention monitoring or follow-up checks if confidence is limited by environment or observability.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Incident Response and Stabilization
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Guide high-pressure response to live or high-impact issues by separating immediate stabilization from deeper root-cause correction.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- A production issue is actively impacting users or operators
|
|
||||||
- A regression needs containment before a complete fix is ready
|
|
||||||
- The team needs a calm sequence for triage, mitigation, and follow-up
|
|
||||||
- Communication and operational clarity matter as much as code changes
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current symptoms, severity, affected users, and timing
|
|
||||||
- Available logs, metrics, alerts, dashboards, and recent changes
|
|
||||||
- Safe rollback, feature flag, degrade, or traffic-shaping options
|
|
||||||
- Stakeholders who need updates and what they need to know
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Stabilize user impact first if a safe containment path exists.
|
|
||||||
- Keep mitigation, diagnosis, and communication distinct but coordinated.
|
|
||||||
- Prefer reversible steps under uncertainty.
|
|
||||||
- Record what is confirmed versus assumed while the incident is active.
|
|
||||||
- After stabilization, convert the incident into structured debugging and prevention work.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Stabilization plan or incident response summary
|
|
||||||
- Clear mitigation status and next actions
|
|
||||||
- Follow-up work for root cause, observability, and prevention
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- User impact reduction is prioritized appropriately.
|
|
||||||
- Risky irreversible changes are avoided under pressure.
|
|
||||||
- Communication is clear enough for collaborators to act.
|
|
||||||
- Post-incident follow-up is not lost after immediate recovery.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note what was mitigated versus actually fixed.
|
|
||||||
- Pair with debugging workflow and observability once the system is stable enough for deeper work.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Architecture Decision Records
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- A meaningful architectural or platform choice has been made
|
|
||||||
- Multiple alternatives were considered and context would otherwise be lost
|
|
||||||
- A decision will affect future implementation, migration, or team habits
|
|
||||||
- You want to prevent repeated re-litigation of the same tradeoff
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- The decision being made
|
|
||||||
- Alternatives considered
|
|
||||||
- Relevant constraints, drivers, and consequences
|
|
||||||
- Current status: proposed, accepted, superseded, or rejected
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Record the decision close to when it is made.
|
|
||||||
- Keep the record concise but concrete enough to survive future context loss.
|
|
||||||
- Explain why the selected option won, not just what it is.
|
|
||||||
- Include consequences so future readers understand the cost of the choice.
|
|
||||||
- Update or supersede older records rather than leaving conflicting guidance unresolved.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A crisp decision record with context, choice, alternatives, and consequences
|
|
||||||
- Status that reflects whether the decision is still tentative or settled
|
|
||||||
- Links to implementation or follow-up docs when useful
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The decision is clear and specific.
|
|
||||||
- Alternatives and tradeoffs are visible.
|
|
||||||
- Future readers can understand the reasoning without redoing the whole discussion.
|
|
||||||
- The record stays short enough to remain useful.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Reference the implementation, technical docs, or migration plan that operationalizes the decision.
|
|
||||||
- Pair with architecture and system design for major system changes.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Onboarding Documentation
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Help new contributors or users become productive quickly by reducing ambiguity, setup friction, and missing context.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Improving setup or first-run guidance
|
|
||||||
- Writing contributor onboarding docs
|
|
||||||
- Creating "start here" guides for internal or external users
|
|
||||||
- Simplifying confusing developer or product entry points
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current setup steps and prerequisites
|
|
||||||
- Common failure points, hidden assumptions, and missing context
|
|
||||||
- Existing onboarding flow and repository conventions
|
|
||||||
- Intended audience: contributor, operator, customer, or teammate
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Optimize for first success, not exhaustiveness.
|
|
||||||
- Put prerequisites, setup order, and validation steps in the order a new person needs them.
|
|
||||||
- Surface gotchas early rather than burying them after failures occur.
|
|
||||||
- Use concrete commands, examples, and expected outcomes when they reduce confusion.
|
|
||||||
- Trim insider jargon unless it is explained.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A cleaner onboarding path with clear first steps
|
|
||||||
- Documentation that reduces setup ambiguity and dead ends
|
|
||||||
- Helpful validation or troubleshooting guidance where needed
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- A new person can tell where to start.
|
|
||||||
- Steps are ordered logically and are easy to verify.
|
|
||||||
- Prerequisites and common failures are not hidden.
|
|
||||||
- The doc avoids assuming too much existing context.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note any setup steps you could not verify directly.
|
|
||||||
- Pair with technical docs when onboarding depends on deeper conceptual explanation.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Technical Documentation
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Create or update documentation that helps developers, operators, or advanced users understand how the system works and how to use it correctly.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Updating docs after engineering changes
|
|
||||||
- Writing usage guides, architecture notes, or operational docs
|
|
||||||
- Explaining APIs, workflows, configuration, or system behavior
|
|
||||||
- Improving stale or incomplete technical documentation
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- The current implementation and the user-visible workflow
|
|
||||||
- Existing docs, terminology, and structure in the repo
|
|
||||||
- Intended audience and their technical depth
|
|
||||||
- Any setup steps, caveats, or common failure points
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Document the real behavior of the system, not the hoped-for design.
|
|
||||||
- Prefer task-oriented structure when users need to get something done.
|
|
||||||
- Use precise terminology that matches the code and UI.
|
|
||||||
- Include examples, prerequisites, and pitfalls when they materially improve clarity.
|
|
||||||
- Keep docs aligned with adjacent pages and avoid fragmenting the source of truth.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear, accurate documentation update or new draft
|
|
||||||
- Audience-appropriate level of technical detail
|
|
||||||
- Explicit caveats, prerequisites, and compatibility notes when relevant
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Instructions are accurate against the current implementation.
|
|
||||||
- The document helps someone complete a real task or understand a real concept.
|
|
||||||
- Terms and examples are consistent with the product and codebase.
|
|
||||||
- Important caveats are easy to find.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention what was verified directly in code versus inferred from context.
|
|
||||||
- Note any related docs that should be updated later to stay consistent.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Content Strategy and SEO
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Create durable content plans and search-aligned messaging that compound over time instead of only supporting one launch moment.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Planning evergreen content around a product area
|
|
||||||
- Improving discoverability for technical or product topics
|
|
||||||
- Aligning content to audience intent and search behavior
|
|
||||||
- Deciding which topics deserve durable written assets
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Audience segments and their recurring questions
|
|
||||||
- Product strengths, proof points, and topic authority
|
|
||||||
- Existing content library and content gaps
|
|
||||||
- Desired business outcome: discovery, education, conversion, or retention
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start from audience intent and recurring problems, not isolated keywords alone.
|
|
||||||
- Organize content into durable themes that the product can support credibly.
|
|
||||||
- Align titles, structure, and calls to action with user intent.
|
|
||||||
- Avoid search-driven copy that weakens clarity or trust.
|
|
||||||
- Prefer content that stays useful as the product evolves.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Content strategy, topic map, or SEO-aware draft direction
|
|
||||||
- Prioritized content opportunities with rationale
|
|
||||||
- Notes on how content connects to product positioning and documentation
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Recommendations reflect real audience needs.
|
|
||||||
- Content ideas support durable value, not shallow traffic grabs.
|
|
||||||
- Search alignment does not distort message clarity.
|
|
||||||
- The strategy can inform multiple future assets.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note which assumptions are based on audience reasoning versus actual search data.
|
|
||||||
- Pair with messaging/positioning and technical docs for strong, credible long-tail content.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Marketing Content
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Create external-facing content that explains, promotes, or launches product capabilities in a way that is accurate, audience-aware, and compelling.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Drafting launch posts, emails, feature pages, announcements, or social content
|
|
||||||
- Turning product or engineering work into outward-facing communication
|
|
||||||
- Adapting one core message into multiple channels
|
|
||||||
- Creating content tied to a release or campaign
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Audience, channel, and desired action
|
|
||||||
- The actual product change or offer being communicated
|
|
||||||
- Supporting proof points, examples, and differentiators
|
|
||||||
- Voice, tone, and length constraints
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Lead with why the audience should care.
|
|
||||||
- Ground claims in the real product and its benefits.
|
|
||||||
- Structure content so it is easy to scan and repurpose.
|
|
||||||
- Tailor tone and density to the channel instead of reusing the same draft everywhere.
|
|
||||||
- Keep technical explanations accurate while translating them into audience-relevant outcomes.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A polished draft for the requested channel
|
|
||||||
- Supporting variations or headline options when useful
|
|
||||||
- Clear call to action where appropriate
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The content is audience-centered, not feature-dump centered.
|
|
||||||
- Claims are specific and defensible.
|
|
||||||
- The narrative is easy to scan and follow.
|
|
||||||
- The output matches the requested medium and length.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- State which audience and channel the draft targets.
|
|
||||||
- Pair with messaging/positioning when the strategic framing is not yet settled.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Messaging and Positioning
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Clarify who the product or feature is for, what value it provides, why it matters now, and how it differs from alternatives.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Defining or refining product narrative
|
|
||||||
- Preparing launches, landing pages, or feature announcements
|
|
||||||
- Choosing how to frame a new capability for a target audience
|
|
||||||
- Aligning product, UX, and marketing language around one story
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Target audience and their pain points
|
|
||||||
- Product capability, strengths, and evidence
|
|
||||||
- Competitive or alternative solutions
|
|
||||||
- Business goal of the messaging effort
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start with audience pain or desired outcome, then connect the product to that need.
|
|
||||||
- Distinguish core value, supporting proof, and differentiators.
|
|
||||||
- Avoid vague slogans unless they are backed by a concrete explanation.
|
|
||||||
- Stress-test the message against realistic alternatives and skeptical readers.
|
|
||||||
- Produce a tight core narrative that other copy can inherit.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear positioning statement or message framework
|
|
||||||
- Defined audience, value proposition, and differentiators
|
|
||||||
- Candidate headlines, pillars, or narrative directions when useful
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The message is specific about audience and value.
|
|
||||||
- Differentiation is real, not generic category language.
|
|
||||||
- Claims are supportable by the product.
|
|
||||||
- The narrative can guide product copy and campaign content consistently.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note open questions about audience, market, or product maturity if they limit confidence.
|
|
||||||
- Pair with product copy or marketing content to turn the narrative into shipped assets.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Product Copy
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Write concise, user-facing product language that is clear, useful, on-brand, and matched to the immediate interface or conversion context.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Naming buttons, labels, helper text, empty states, and error messages
|
|
||||||
- Tightening landing page or feature page copy
|
|
||||||
- Improving clarity and persuasion in product-adjacent text
|
|
||||||
- Rewriting awkward or confusing interface wording
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Audience, goal, and context of the text
|
|
||||||
- Current product voice and terminology
|
|
||||||
- UI constraints such as length, hierarchy, and surrounding elements
|
|
||||||
- Desired action or decision the copy should support
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Optimize for clarity first, persuasion second, cleverness last.
|
|
||||||
- Use the words users expect based on the product and task.
|
|
||||||
- Match the level of confidence and urgency to the action being requested.
|
|
||||||
- Keep text tight and scannable, especially in UI contexts.
|
|
||||||
- Offer alternatives when tone or positioning is uncertain.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Final copy or strong candidate options
|
|
||||||
- Brief rationale when choosing between meaningful directions
|
|
||||||
- Notes on character, tone, or placement constraints when relevant
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Copy is clear on first read.
|
|
||||||
- The wording fits the user's moment and intent.
|
|
||||||
- Claims are credible and specific.
|
|
||||||
- Text length is appropriate to the surface.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note if final selection depends on brand voice or product strategy not yet defined.
|
|
||||||
- Pair with UX review for interface clarity and with messaging/positioning for strategic alignment.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# API and Backend Work
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Guide server-side, service, API, data, and integration changes with attention to contracts, compatibility, failure handling, and operational impact.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Modifying endpoints, handlers, services, jobs, or data flows
|
|
||||||
- Adding or changing schemas, persistence, or integration behavior
|
|
||||||
- Working on backend business logic or infrastructure-facing code
|
|
||||||
- Investigating performance, reliability, or contract issues on the server side
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- API contracts, schema, storage models, and service boundaries
|
|
||||||
- Existing validation, auth, error handling, and observability patterns
|
|
||||||
- Compatibility constraints for clients, data, and deployments
|
|
||||||
- Current tests and representative request or event flows
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Trace the full request or job lifecycle before changing a boundary.
|
|
||||||
- Preserve compatibility intentionally or document the break clearly.
|
|
||||||
- Handle validation, authorization, error responses, and retries in line with existing system behavior.
|
|
||||||
- Consider migration, rollout, and operational visibility when data or contracts change.
|
|
||||||
- Add or update tests at the right layer for the change.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Working backend change with contract implications made explicit
|
|
||||||
- Notes on schema, config, data, or rollout impact
|
|
||||||
- Verification results covering the critical paths
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Inputs and outputs are validated appropriately.
|
|
||||||
- Failure handling is explicit and consistent.
|
|
||||||
- Compatibility and migration impact are understood.
|
|
||||||
- Logging, metrics, or observability concerns are addressed when relevant.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Call out any required coordination with frontend, data migration, configuration, or deployment steps.
|
|
||||||
- Note backwards-incompatible changes clearly and early.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Architecture and System Design
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Shape meaningful technical direction so systems stay understandable, evolvable, and aligned with product needs over time.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Designing a major feature or subsystem
|
|
||||||
- Changing service boundaries, module boundaries, or core data flow
|
|
||||||
- Evaluating multiple implementation approaches with long-term consequences
|
|
||||||
- Preparing work that will influence maintainability, scale, or team velocity
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current architecture, boundaries, and pain points
|
|
||||||
- Product goals, scale expectations, and reliability constraints
|
|
||||||
- Existing patterns, platform constraints, and team operating model
|
|
||||||
- Compatibility, migration, and rollout concerns
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start from the user or system outcome, then identify the simplest architecture that supports it well.
|
|
||||||
- Make tradeoffs explicit: complexity, performance, reliability, maintainability, and delivery speed.
|
|
||||||
- Preserve useful existing boundaries unless there is a clear reason to change them.
|
|
||||||
- Prefer designs that are easy to operate and easy for the team to understand.
|
|
||||||
- Document why the chosen path is better than the main alternatives.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear recommended design or architecture direction
|
|
||||||
- Explicit tradeoffs and constraints
|
|
||||||
- Interfaces, boundaries, and rollout considerations that matter for implementation
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The design solves the actual problem, not a hypothetical future one.
|
|
||||||
- Tradeoffs are named clearly enough to guide later decisions.
|
|
||||||
- Complexity is justified by concrete needs.
|
|
||||||
- Operational and migration consequences are not ignored.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Pair with architecture decision records when the choice should be preserved for future contributors.
|
|
||||||
- Call out which parts are decided versus intentionally deferred.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Code Review
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Review code with a bug-finding mindset that prioritizes correctness, regressions, risky assumptions, edge cases, and missing tests over style commentary.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Reviewing a pull request or patch
|
|
||||||
- Auditing a risky change before merge
|
|
||||||
- Evaluating whether a change is safe to ship
|
|
||||||
- Checking for test and documentation gaps
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- The diff or changed files
|
|
||||||
- Nearby code paths and contracts affected by the change
|
|
||||||
- Existing tests, especially those intended to cover the modified behavior
|
|
||||||
- Context on expected behavior, rollout risk, and compatibility requirements
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start with correctness, then move to regressions, then test gaps, then maintainability risks.
|
|
||||||
- Trace changed code through call sites, error paths, and data flow rather than reading only the edited lines in isolation.
|
|
||||||
- Focus comments on issues that materially affect behavior, safety, or maintainability.
|
|
||||||
- Be explicit about severity and the concrete consequence of each issue.
|
|
||||||
- Keep summary brief after listing the findings.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A prioritized list of findings with clear reasoning
|
|
||||||
- Open questions or assumptions that affect confidence
|
|
||||||
- Brief summary of overall risk after the findings
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Findings identify real behavior or verification risk, not cosmetic preferences.
|
|
||||||
- Severity is proportional to user impact and likelihood.
|
|
||||||
- Missing tests are called out where they reduce confidence materially.
|
|
||||||
- If no issues are found, residual risk and coverage gaps are still noted.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Include file references and tight line references when available.
|
|
||||||
- Distinguish confirmed issues from lower-confidence concerns.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Database Migrations and Data Evolution
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Adding, removing, or changing database schema
|
|
||||||
- Backfilling or transforming data
|
|
||||||
- Introducing compatibility windows between old and new code
|
|
||||||
- Planning rollout for data-sensitive changes
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current schema, access patterns, and data volume
|
|
||||||
- Migration tooling and deployment model
|
|
||||||
- Compatibility requirements across services, jobs, or clients
|
|
||||||
- Rollback constraints and data recovery options
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract.
|
|
||||||
- Minimize lock risk, data loss risk, and long-running migration risk.
|
|
||||||
- Consider how old and new code will coexist during rollout.
|
|
||||||
- Define verification steps for schema state and critical data correctness.
|
|
||||||
- Document irreversible steps and operator actions clearly.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Safe migration plan or implementation
|
|
||||||
- Compatibility and rollout notes
|
|
||||||
- Verification and rollback considerations
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The migration is safe for the repository's deployment model.
|
|
||||||
- Data correctness is protected during and after rollout.
|
|
||||||
- Backwards and forwards compatibility are considered when needed.
|
|
||||||
- Irreversible or risky steps are made explicit.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Call out sequencing requirements across application code, migrations, and background jobs.
|
|
||||||
- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Dependency Lifecycle Management
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Keep dependencies healthy over time by balancing security, compatibility, maintainability, and upgrade cost.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Upgrading libraries, frameworks, runtimes, or tooling
|
|
||||||
- Auditing dependency risk or staleness
|
|
||||||
- Reducing upgrade backlog and ecosystem drift
|
|
||||||
- Planning how to adopt breaking changes safely
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current dependency versions and their role in the system
|
|
||||||
- Changelogs, upgrade guides, and breaking changes
|
|
||||||
- Existing test coverage and high-risk integration points
|
|
||||||
- Security, support-window, or maintenance concerns
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Prefer focused upgrade batches that are easy to validate and revert.
|
|
||||||
- Separate mechanical version bumps from behavior-changing adaptation when possible.
|
|
||||||
- Read authoritative release notes before changing usage patterns.
|
|
||||||
- Verify the highest-risk integration paths, not just installation success.
|
|
||||||
- Capture follow-up work when a safe incremental upgrade leaves known deprecated patterns behind.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Upgrade plan or completed upgrade with adaptation notes
|
|
||||||
- Risk summary for changed dependencies
|
|
||||||
- Verification results and known remaining debt
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The upgrade reduces risk or maintenance burden meaningfully.
|
|
||||||
- Breaking changes are understood before implementation.
|
|
||||||
- Validation covers the most likely failure surfaces.
|
|
||||||
- Residual deprecations or postponed steps are documented clearly.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note whether the work is a full upgrade, a safe intermediate step, or a reconnaissance pass.
|
|
||||||
- Pair with test strategy and release/change summary when adoption affects developer workflow or runtime behavior.
|
|
||||||
@@ -1,48 +0,0 @@
|
|||||||
# Feature Implementation
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Guide implementation of new behavior or meaningful changes to existing behavior with a bias toward working software, repository alignment, and practical verification.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Building a new feature
|
|
||||||
- Expanding an existing workflow
|
|
||||||
- Making a multi-file change that affects user or developer behavior
|
|
||||||
- Turning a scoped request into implemented code
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Relevant entrypoints, modules, and surrounding patterns
|
|
||||||
- Existing interfaces, types, schema, and tests
|
|
||||||
- User goal, success criteria, constraints, and impacted surfaces
|
|
||||||
- Any repository instructions that override generic defaults
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Inspect the codebase before editing and identify the smallest coherent change set.
|
|
||||||
- Prefer existing patterns over introducing novel structure unless the current patterns are clearly limiting.
|
|
||||||
- Implement end-to-end behavior, not just partial scaffolding, when feasible.
|
|
||||||
- Keep logic changes close to the relevant module boundaries and avoid unrelated cleanup unless it materially helps the task.
|
|
||||||
- Validate with targeted tests, builds, or manual checks appropriate to the repository.
|
|
||||||
- Update docs, examples, or change notes when the feature alters usage or expectations.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A working implementation or a clearly explained blocker
|
|
||||||
- Concise summary of what changed and why
|
|
||||||
- Validation results and any gaps that remain
|
|
||||||
- Notes on follow-up work only when it is genuinely important
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The change matches the stated goal and avoids unrelated churn.
|
|
||||||
- Naming, structure, and style fit the existing codebase.
|
|
||||||
- Errors, edge cases, and obvious failure paths are handled.
|
|
||||||
- Verification is appropriate for the size and risk of the change.
|
|
||||||
- User-facing or developer-facing behavior changes are documented when needed.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention touched subsystems and any assumptions made because the repo did not answer them.
|
|
||||||
- Call out migration or rollout concerns if the feature affects data, config, or compatibility.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Frontend UI Implementation
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Guide interface implementation that balances correctness, usability, clarity, performance, and consistency with the existing product experience.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Building or updating pages, components, and interactions
|
|
||||||
- Implementing client-side state or view logic
|
|
||||||
- Adjusting layout, form flows, states, and visual feedback
|
|
||||||
- Shipping UI changes tied to product behavior
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Existing design system, component patterns, and styling conventions
|
|
||||||
- User flow, content requirements, and responsive constraints
|
|
||||||
- State, API, and error/loading behavior tied to the UI
|
|
||||||
- Current tests, stories, screenshots, or acceptance criteria if available
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Preserve the established visual language unless the task explicitly calls for a new direction.
|
|
||||||
- Design for the full experience: loading, empty, error, success, and edge states.
|
|
||||||
- Keep interaction logic understandable and avoid overengineering small UI behavior.
|
|
||||||
- Use content, hierarchy, and spacing intentionally so the UI communicates clearly.
|
|
||||||
- Validate on the most important screen sizes or states that the repository can reasonably support.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- A functional UI change that is coherent visually and behaviorally
|
|
||||||
- Clear notes on user-facing behavior and state handling
|
|
||||||
- Verification appropriate to the stack, such as tests, stories, or manual checks
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The UI is understandable without hidden assumptions.
|
|
||||||
- Important states are handled, not just the happy path.
|
|
||||||
- Visual and code patterns fit the existing app.
|
|
||||||
- Accessibility, responsiveness, and copy quality are considered.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention any UX debts, unresolved visual questions, or browser/device gaps that remain.
|
|
||||||
- Pair with UX review or product copy when usability or wording is central to the task.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Maintenance and Technical Debt Planning
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Turn vague maintenance needs into a practical, sequenced plan that improves delivery speed, reliability, and future change safety over time.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- The codebase has accumulated risky or slowing debt
|
|
||||||
- A team needs to prioritize cleanup against feature work
|
|
||||||
- Repeated friction suggests structural maintenance investment is overdue
|
|
||||||
- You need to explain why maintenance work matters in product terms
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Known pain points, repeated failures, and slow areas in delivery
|
|
||||||
- Architectural hotspots, obsolete patterns, and fragile dependencies
|
|
||||||
- Team constraints, roadmap pressure, and acceptable disruption
|
|
||||||
- Evidence of cost: incidents, churn, slowed feature work, or support burden
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Focus on debt that materially changes future delivery, reliability, or risk.
|
|
||||||
- Group issues into themes rather than a flat list of annoyances.
|
|
||||||
- Prioritize by impact, urgency, and dependency relationships.
|
|
||||||
- Prefer incremental sequences that can ship safely between feature work.
|
|
||||||
- Translate maintenance value into outcomes the team can defend.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Prioritized maintenance plan or backlog proposal
|
|
||||||
- Clear rationale for what should happen now versus later
|
|
||||||
- Sequencing guidance and expected payoff
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Recommendations are tied to real delivery or reliability pain.
|
|
||||||
- Prioritization is explicit and defensible.
|
|
||||||
- The plan is incremental enough to execute.
|
|
||||||
- Work is framed in terms of reduced risk or increased velocity, not vague cleanliness.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note what evidence would strengthen or change the prioritization.
|
|
||||||
- Pair with roadmap and opportunity prioritization when balancing debt against new initiatives.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Observability and Operability
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Make systems easier to understand, debug, and run by improving signals, diagnostics, and operational readiness around important behavior.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- A system is hard to diagnose in production or staging
|
|
||||||
- New functionality needs useful logs, metrics, traces, or alerts
|
|
||||||
- Operational ownership is unclear during failures or rollout
|
|
||||||
- Reliability work needs better visibility before deeper changes
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Critical workflows, failure modes, and current diagnostic signals
|
|
||||||
- Existing logging, metrics, tracing, dashboards, and alerts
|
|
||||||
- Operator needs during rollout, incident response, and debugging
|
|
||||||
- Noise constraints and performance or cost considerations
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Instrument the questions a responder will need answered during failure.
|
|
||||||
- Prefer signals tied to user-impacting behavior over vanity metrics.
|
|
||||||
- Make logs structured and actionable when possible.
|
|
||||||
- Add observability close to important boundaries and state transitions.
|
|
||||||
- Keep signal quality high by avoiding low-value noise.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Improved observability or an operability plan for the target area
|
|
||||||
- Clear explanation of what new signals reveal
|
|
||||||
- Notes on alerting, dashboard, or rollout support when relevant
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Signals help detect and diagnose meaningful failures.
|
|
||||||
- Instrumentation is focused and not excessively noisy.
|
|
||||||
- Operational usage is considered, not just implementation convenience.
|
|
||||||
- Added visibility maps to critical user or system outcomes.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention what incidents or debugging tasks the new observability should make easier.
|
|
||||||
- Pair with debugging workflow, incident response, or performance optimization when diagnosis is the main bottleneck.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Performance Optimization
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Improve responsiveness and efficiency by focusing on the bottlenecks that matter most to users, systems, or operating cost.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Investigating slow pages, endpoints, jobs, or queries
|
|
||||||
- Reducing memory, CPU, network, or rendering overhead
|
|
||||||
- Preventing regressions in critical paths
|
|
||||||
- Prioritizing optimization work with limited time
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Performance symptoms, target metrics, and critical user or system paths
|
|
||||||
- Existing measurements, profiles, logs, traces, or benchmarks
|
|
||||||
- Current architecture and known hot spots
|
|
||||||
- Acceptable tradeoffs in complexity, cost, and feature scope
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Measure or inspect evidence before optimizing.
|
|
||||||
- Focus on the dominant bottleneck rather than broad cleanup.
|
|
||||||
- Prefer changes that improve the critical path without making the system harder to maintain.
|
|
||||||
- Re-measure after changes when possible.
|
|
||||||
- Capture the conditions under which the optimization matters so future work does not cargo-cult it.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Bottleneck diagnosis and recommended or implemented improvement
|
|
||||||
- Before-and-after evidence when available
|
|
||||||
- Notes on tradeoffs, limits, and remaining hot spots
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Optimization targets a real bottleneck.
|
|
||||||
- Claimed gains are grounded in evidence, not assumption alone.
|
|
||||||
- Complexity added by the optimization is justified.
|
|
||||||
- Regression risk is considered for correctness and maintainability.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note whether the result is measured, estimated, or hypothesis-driven.
|
|
||||||
- Pair with observability and operability when instrumentation is weak.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Refactoring
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Improve code structure, readability, maintainability, or modularity without intentionally changing externally observable behavior.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Simplifying complex logic
|
|
||||||
- Extracting clearer abstractions
|
|
||||||
- Reducing duplication or coupling
|
|
||||||
- Preparing code for future work while preserving behavior
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Current behavior and tests that define expected outcomes
|
|
||||||
- Structural pain points in the relevant modules
|
|
||||||
- Constraints around public APIs, compatibility, or performance
|
|
||||||
- Existing patterns for abstraction and module boundaries
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Preserve behavior intentionally and define what must remain unchanged before editing.
|
|
||||||
- Favor small, reviewable moves over sweeping rewrites unless the code is already unsafe to work in incrementally.
|
|
||||||
- Keep interface changes minimal and justified.
|
|
||||||
- Add or strengthen tests when behavior preservation is important and current coverage is weak.
|
|
||||||
- Separate cleanup that supports the refactor from unrelated aesthetic changes.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Cleaner code with behavior preserved
|
|
||||||
- Clear explanation of the structural improvement
|
|
||||||
- Verification evidence that the refactor did not break expected behavior
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Intended behavior is unchanged unless explicitly documented otherwise.
|
|
||||||
- The resulting structure is easier to understand or extend.
|
|
||||||
- Interface changes are minimal, justified, and documented.
|
|
||||||
- Added complexity is avoided unless it buys meaningful maintainability.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Call out any areas where behavior preservation is inferred rather than strongly verified.
|
|
||||||
- Note future cleanup opportunities only if they naturally follow from the refactor.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Release and Change Summary
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Explain shipped or proposed changes clearly for developers, operators, collaborators, or end users, with emphasis on what changed, why it matters, and what action is required.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Writing release notes or changelog entries
|
|
||||||
- Summarizing completed engineering work
|
|
||||||
- Explaining migration or rollout impact
|
|
||||||
- Turning technical changes into clear stakeholder communication
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- The actual code or product changes
|
|
||||||
- Intended audience and their level of technical depth
|
|
||||||
- Any rollout, migration, compatibility, or operational considerations
|
|
||||||
- Linked docs, issues, or feature context that explains why the change exists
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Lead with the user-meaningful change, not internal implementation trivia.
|
|
||||||
- Group related changes into a few clear themes rather than a raw diff dump.
|
|
||||||
- Call out required actions, migrations, or risks explicitly.
|
|
||||||
- Tailor the level of detail to the audience.
|
|
||||||
- Keep the summary accurate to the implementation that actually landed.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear release notes, summary, or change communication draft
|
|
||||||
- Audience-appropriate explanation of impact and required action
|
|
||||||
- Explicit mention of follow-up items only when relevant
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The summary matches the real change, not the original intent alone.
|
|
||||||
- Important caveats, migrations, and compatibility notes are visible.
|
|
||||||
- Wording is concise and easy to scan.
|
|
||||||
- Audience knowledge level is respected.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Say who the summary is for and what medium it targets if that is not obvious.
|
|
||||||
- Pair with technical docs or marketing skills when the output needs deeper explanation or stronger positioning.
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
# Repository Exploration
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Rapidly build accurate context before implementation, debugging, or planning by identifying the right files, flows, conventions, and constraints in the repository.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Starting in an unfamiliar repository
|
|
||||||
- Locating the right implementation area for a request
|
|
||||||
- Understanding current architecture before proposing changes
|
|
||||||
- Reducing ambiguity in a vague task
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Repository layout, entrypoints, and key modules
|
|
||||||
- Build, test, and dependency configuration
|
|
||||||
- Existing patterns for similar features or workflows
|
|
||||||
- Any local instructions, docs, or conventions already in the repo
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start broad, then narrow quickly to the files and flows relevant to the task.
|
|
||||||
- Favor authoritative sources in the repo such as configs, types, interfaces, docs, and existing implementations.
|
|
||||||
- Identify where decisions are already made by the codebase so you do not reinvent them.
|
|
||||||
- Summarize findings in terms of how they affect the next action.
|
|
||||||
- Stop exploring once the path to execution is clear enough.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Concise map of the relevant code paths and conventions
|
|
||||||
- Recommended starting points for changes or further investigation
|
|
||||||
- Key unknowns that still require validation
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Exploration answers practical implementation questions rather than producing generic architecture prose.
|
|
||||||
- Findings are tied to concrete files, modules, or workflows.
|
|
||||||
- Enough context is gathered to act confidently without over-reading the entire repo.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention the most relevant files, commands, and repo conventions discovered.
|
|
||||||
- Flag ambiguous areas where multiple plausible implementation paths exist.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Security Review and Hardening
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Reduce avoidable security risk by reviewing trust boundaries, sensitive data handling, exposure paths, and abuse opportunities in the relevant system area.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Shipping authentication, authorization, input handling, or sensitive workflows
|
|
||||||
- Reviewing an externally exposed feature or API
|
|
||||||
- Auditing risky changes for common security failures
|
|
||||||
- Hardening an existing system area with known gaps
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Trust boundaries, user roles, and entry points
|
|
||||||
- Sensitive data flows, secrets, tokens, or privileged operations
|
|
||||||
- Existing auth, validation, logging, and rate limiting patterns
|
|
||||||
- Relevant compliance or threat concerns if known
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Start with who can do what, from where, and with which inputs.
|
|
||||||
- Check validation, authorization, data exposure, secret handling, and abuse resistance.
|
|
||||||
- Prefer concrete mitigations over vague warnings.
|
|
||||||
- Align with existing security controls unless they are clearly insufficient.
|
|
||||||
- Call out unverified areas when the environment or tooling limits confidence.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Concrete risks found or a scoped hardening plan
|
|
||||||
- Recommended mitigations tied to the actual threat surface
|
|
||||||
- Clear statement of confidence and any blind spots
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Review covers the real trust boundaries and attack surface.
|
|
||||||
- Findings describe exploit consequence, not just theoretical concern.
|
|
||||||
- Mitigations are practical for the system and team.
|
|
||||||
- Residual risk is visible where hardening is incomplete.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Separate must-fix risks from defense-in-depth improvements.
|
|
||||||
- Pair with code review, API/backend work, and observability when the issue spans implementation and detection.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Test Strategy
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Choose and evaluate the right level of verification so changes are covered proportionally to their risk, behavior, and maintenance cost.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Adding or updating tests for a feature or bug fix
|
|
||||||
- Deciding what verification is necessary before shipping
|
|
||||||
- Auditing coverage gaps in existing code
|
|
||||||
- Designing regression protection for risky areas
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- The behavior being changed or protected
|
|
||||||
- Current test layout, tooling, and conventions
|
|
||||||
- Known failure modes, regressions, or edge cases
|
|
||||||
- Constraints on test speed, environment, and confidence needs
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Match test level to risk: unit for logic, integration for boundaries, end-to-end for critical workflows.
|
|
||||||
- Prefer the smallest test that meaningfully protects the behavior.
|
|
||||||
- Cover success paths, likely failure paths, and regressions suggested by the change.
|
|
||||||
- Reuse existing fixtures and patterns where possible.
|
|
||||||
- If tests are not feasible, define alternate validation steps and explain the gap.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Specific recommended or implemented tests
|
|
||||||
- Clear rationale for test level and scope
|
|
||||||
- Any remaining uncovered risks or follow-up test ideas
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Tests target behavior, not implementation trivia.
|
|
||||||
- Coverage includes the change's highest-risk paths.
|
|
||||||
- Test design fits repository conventions and runtime cost expectations.
|
|
||||||
- Non-tested areas are called out explicitly when important.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note flaky, expensive, or environment-dependent checks separately from fast local confidence checks.
|
|
||||||
- Mention whether the test plan is implemented, recommended, or partially blocked.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Accessibility Review
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Improve inclusive usability by checking whether interfaces are operable, understandable, and robust for people using different devices, input methods, and assistive technologies.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Reviewing or implementing user-facing UI
|
|
||||||
- Checking forms, dialogs, navigation, or interactive states
|
|
||||||
- Improving keyboard support, semantics, contrast, or feedback
|
|
||||||
- Raising the quality bar for long-lived interface patterns
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Relevant screens, components, and interaction flows
|
|
||||||
- Existing design system, semantic patterns, and accessibility goals
|
|
||||||
- Keyboard, screen reader, focus, contrast, and motion considerations
|
|
||||||
- Known constraints in the stack or component library
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Check the main user path with keyboard and semantics in mind first.
|
|
||||||
- Review labels, focus order, state announcements, contrast, and error clarity.
|
|
||||||
- Prioritize issues that block task completion or create major confusion.
|
|
||||||
- Recommend changes that fit the current implementation model and team capacity.
|
|
||||||
- Treat accessibility as product quality, not a final polish pass.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear accessibility findings or implementation guidance
|
|
||||||
- Prioritized fixes by impact on usability and inclusion
|
|
||||||
- Notes on what was inspected directly versus inferred
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Findings focus on real interaction barriers.
|
|
||||||
- Recommendations are specific enough to implement.
|
|
||||||
- The review covers both semantics and user experience.
|
|
||||||
- High-impact accessibility gaps are surfaced early.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Mention whether checks were code-based, visual, or manually reasoned.
|
|
||||||
- Pair with frontend UI implementation and design system consistency when shipping durable fixes.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# Design System and UI Consistency
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Promote reusable, scalable UI patterns so the interface stays coherent as the product grows.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- A UI area is drifting from existing patterns
|
|
||||||
- Reusable components or patterns should replace one-off implementations
|
|
||||||
- A feature adds new patterns that may affect future screens
|
|
||||||
- You want to improve consistency without a full redesign
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Existing components, tokens, layout patterns, and style conventions
|
|
||||||
- The new or changed UI requirements
|
|
||||||
- Current inconsistencies, duplication, or local hacks
|
|
||||||
- Constraints from the stack, theme system, or design resources
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Reuse existing components and conventions before inventing new ones.
|
|
||||||
- Introduce new patterns only when the current system cannot express the need cleanly.
|
|
||||||
- Optimize for maintainability and consistency, not just a one-screen outcome.
|
|
||||||
- Keep component APIs and styling patterns understandable.
|
|
||||||
- Document new reusable patterns when they materially expand the design system.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- More consistent UI implementation or a clear plan for pattern consolidation
|
|
||||||
- Notes on reused versus newly introduced patterns
|
|
||||||
- Guidance on where the system should expand carefully
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- The UI becomes more coherent, not more fragmented.
|
|
||||||
- Reuse is meaningful and does not force a poor fit.
|
|
||||||
- New abstractions are justified by repeated or durable need.
|
|
||||||
- The solution helps future features move faster.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Note whether the work is local cleanup, reusable component work, or system-level direction.
|
|
||||||
- Pair with UX review and frontend implementation when consistency changes affect behavior and clarity.
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
# UX Review
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
Evaluate an interface or flow for clarity, usability, friction, trust, and task completion quality, then turn those observations into actionable improvements.
|
|
||||||
|
|
||||||
## When to use
|
|
||||||
|
|
||||||
- Reviewing a screen or flow before or after implementation
|
|
||||||
- Looking for usability issues in forms, navigation, settings, or onboarding
|
|
||||||
- Improving hierarchy, copy clarity, state handling, or feedback
|
|
||||||
- Assessing whether an interface supports the intended user goal well
|
|
||||||
|
|
||||||
## Inputs to gather
|
|
||||||
|
|
||||||
- Screens, flows, components, or descriptions of the experience
|
|
||||||
- Target user goal and success criteria
|
|
||||||
- Existing design system or product patterns
|
|
||||||
- Constraints such as device, context, accessibility, or content requirements
|
|
||||||
|
|
||||||
## How to work
|
|
||||||
|
|
||||||
- Review from the user's task perspective rather than from the component tree outward.
|
|
||||||
- Check whether the next action is obvious at each step.
|
|
||||||
- Evaluate hierarchy, wording, spacing, feedback, and state transitions together.
|
|
||||||
- Prioritize issues by how much they block comprehension, confidence, or completion.
|
|
||||||
- Suggest improvements that fit the current product language unless redesign is requested.
|
|
||||||
|
|
||||||
## Output expectations
|
|
||||||
|
|
||||||
- Clear list of UX issues or strengths
|
|
||||||
- Prioritized recommendations with rationale
|
|
||||||
- Notes on where UI changes, copy changes, or research would help most
|
|
||||||
|
|
||||||
## Quality checklist
|
|
||||||
|
|
||||||
- Feedback is tied to user outcomes, not vague aesthetic preference.
|
|
||||||
- Important states such as empty, loading, error, and success are considered.
|
|
||||||
- Recommendations are specific enough to act on.
|
|
||||||
- Suggestions fit the product's current level of complexity and style.
|
|
||||||
|
|
||||||
## Handoff notes
|
|
||||||
|
|
||||||
- Distinguish between usability issues, visual polish issues, and copy issues.
|
|
||||||
- Pair with frontend implementation or product copy when turning review into shipped changes.
|
|
||||||
Reference in New Issue
Block a user