docs: establish Stackable product discovery brain

second-brain/README.md

@@ -0,0 +1,19 @@
+# Stackable Second Brain
+
+An Obsidian-compatible, repository-local knowledge bank for the Stackable product effort.
+
+## Start here
+
+- [[product/brief]] — captured product direction and explicit constraints
+- [[product/research-blacksmith]] — competitor baseline and opportunity framing
+- [[product/decision-log]] — durable decisions and open questions
+- [[wayfinder/stackable-product-map]] — planning map and known frontier
+- [[skills/index]] — preserved skill instructions and discovery output
+- [[sessions/2026-08-21-discovery]] — this session's running record
+
+## Conventions
+
+- Keep decisions concise, dated, and linked to source notes.
+- Store raw skill output without edits in `skills/`.
+- Keep research claims linked to a source.
+- Do not put secrets, tokens, customer data, or credentials in this vault.

second-brain/product/brief.md

@@ -0,0 +1,29 @@
+# Stackable — Product Brief (captured)
+
+## Product intent
+
+Stackable is a CI maintainability platform and CLI for teams using GitHub Actions. It should help teams understand, improve, create, and keep CI/CD healthy rather than operate faster CI runners. The reference competitor is Blacksmith, but Stackable's proposed category is CI maintainability.
+
+## Requested capabilities (unprioritized)
+
+- Full-scale CI/CD monitoring and a digital-side dashboard for active pull requests and pull-request state.
+- A self-updating pull-request comment/report that refreshes on each relevant commit and/or new comment.
+- A polished current-state visualization, selected platform information, and GitHub comment integration.
+- AI-assisted CI/CD setup: describe the desired workflow, review an iterative proposal, and produce CI/CD configuration.
+- Team/organization-ready operations.
+- Web application and CLI for people and agents to manage and run needed work.
+- Design priorities: efficiency, speed, stability, maintainability, and a notably good interface.
+
+## Explicit design constraints
+
+- Palette: purple, onyx, silver, and black.
+- Fonts: Geist and Satoshi.
+- ~~Use a realistic keyboard image for dashboard/product visuals; no synthetic SVG keyboard approximation.~~ Withdrawn by the product owner on 2026-08-21; do not include a keyboard image.
+- Do not use Lucide. Prefer Iconoir icons.
+- Use plain, precise, non-generic user-facing language; review UI copy with an unslop-oriented pass.
+- Treat Watermelon as the first source for UI components, layouts, interactions, and animations. The brief also names ReactBits, Aceternity UI, and Shoogle as sources to investigate. Do not hand-roll components before source suitability is verified.
+- The request mentions a `Design.md` skill/reference, but no such file exists in the checkout yet.
+
+## Generated PR-status visualization
+
+Stackable must generate a functional, deterministic, code-rendered status visualization for use alongside GitHub comments. It should update from API-backed current state, selected CI platform, and related GitHub context. SVG is acceptable as an output format because it is generated from verified state, styled intentionally, and serves operational information; it must never be AI-generated decorative art.

second-brain/product/decision-log.md

@@ -0,0 +1,43 @@
+# Decision Log
+
+## Confirmed preferences
+
+- **2026-08-21 — Product category:** CI maintainability, not CI runner infrastructure.
+- **2026-08-21 — Surfaces:** web application plus agent-friendly CLI.
+- **2026-08-21 — GitHub integration:** PR state and auto-updating reports are central.
+- **2026-08-21 — Visual direction:** purple / onyx / silver / black; Geist + Satoshi; Iconoir rather than Lucide.
+- **2026-08-21 — Knowledge management:** keep a repository-local Obsidian-compatible second brain.
+- **2026-08-21 — Initial audience:** serve both small GitHub Actions engineering teams and individual developers/coding agents, with shared CI intelligence rather than separate products.
+- **2026-08-21 — v1 scope:** the first public version must include PR CI health, AI CI/CD authoring, and organization CI management together; sequence delivery internally as needed, but do not present the first release as a single-pillar tool.
+- **2026-08-21 — GitHub boundary:** support GitHub.com in v1; defer GitHub Enterprise Server compatibility.
+- **2026-08-21 — AI change authority:** authorized users and agents may directly apply CI/CD changes in v1.
+- **2026-08-21 — Direct-write policy:** organization administrators select the branches Stackable may modify directly. The policy must be visible, auditable, and enforceable in both web and CLI flows.
+- **2026-08-21 — Identity:** use a GitHub App for organization/repository access, GitHub OAuth for people, and device-flow/scoped API tokens for CLI users and agents.
+- **2026-08-21 — CI data boundary:** retain structured CI metadata and bounded failure excerpts by default; link to GitHub for complete logs. Do not ingest full logs by default.
+- **2026-08-21 — CI provider scope:** Stackable supports GitHub Actions, CircleCI, and Buildkite from day one, while GitHub.com remains the source-control boundary.
+- **2026-08-21 — Dashboard direction:** expose PR command-center work, organization health, and AI workflow creation as three equal top-level workspaces.
+- **2026-08-21 — Keyboard visual:** withdrawn; do not include a keyboard image in the product UI.
+- **2026-08-21 — Organization authorization:** use four roles—Owner, Admin, Member, and scoped Agent—with policies enforced consistently across web and CLI.
+- **2026-08-21 — Agent interface:** ship a CLI/API and a first-class MCP server in v1.
+- **2026-08-21 — AI authoring flow:** use a staged Review Canvas—intent, repository-aware interview, plan/assumptions, diff, validation, explicit apply, and audit record. The interview must probe deeply in the same one-question-at-a-time style used for product discovery.
+- **2026-08-21 — AI workflow validation:** use provider-aware static validation plus a second, adversarial AI review that checks the proposed change against the user's directive and deliberately hunts for omissions, unsafe assumptions, and likely issues. Do not require a preview run in v1.
+- **2026-08-21 — Direct-write rollback:** detect regressions and propose an authorized revert; do not automatically revert or merely observe.
+- **2026-08-21 — PR report hierarchy:** show one clear next action first, then the pipeline/state map, then health or risk context.
+- **2026-08-21 — PR risk signal:** compute risk from transparent, deterministic, inspectable factors; do not make an AI judgment the primary score.
+- **2026-08-21 — Onboarding:** a guided organization setup installs the GitHub App, connects CI providers, selects repositories and writable branches, then supplies CLI/MCP setup.
+- **2026-08-21 — CD boundary:** Stackable creates and maintains deployment configuration and monitors deployment state, but does not initiate deployments in v1.
+- **2026-08-21 — PR-state visualization:** generate an API-backed, deterministic, code-rendered multi-provider status strip for use beside GitHub comments. SVG is permitted as a functional output format—not as AI-generated decoration. It is a live current-state render because Stackable deletes and replaces its prior canonical comment.
+- **2026-08-21 — State ingestion:** use provider webhooks for immediate updates, backed by adaptive polling that reconciles missed or unsupported events.
+- **2026-08-21 — PR comment cadence:** debounce bursts of provider events; refresh immediately for terminal failure/recovery or manual refresh, otherwise coalesce updates for roughly 30–60 seconds.
+- **2026-08-21 — Dashboard density:** use a balanced product workspace with comfortable spacing and operational detail available through filters and drill-ins.
+- **2026-08-21 — Status color:** purple owns brand, selection, and focus. Use muted semantic green, amber, and red for CI status, always paired with an Iconoir mark and text.
+- **2026-08-21 — Application stack:** use a TypeScript monorepo with Next.js, Tailwind, managed Postgres, background job workers, and a Node CLI/MCP package. Deploy the web application on Vercel.
+- **2026-08-21 — Background jobs:** use Inngest for webhook processing, provider reconciliation, SVG rendering, and GitHub comment refreshes.
+
+## Open decisions
+
+- The first repository type and workflow to optimize for.
+- GitHub App-only versus additional OAuth needs and other SCM support boundaries.
+- The PR report's exact update/reposition algorithm. Direction: a Check Run plus a canonical report that is kept as the latest PR comment. Repost on material CI lifecycle changes or an explicit refresh; edit in place for smaller changes.
+- Tenancy, organization roles, retention, and security model.
+- Real-time update model and operational limits.

second-brain/product/research-blacksmith.md

@@ -0,0 +1,32 @@
+# Research — Blacksmith baseline
+
+_Date researched: 2026-08-21_
+
+## What Blacksmith appears to provide
+
+Blacksmith is a managed, drop-in GitHub Actions runner replacement: teams change runner labels while retaining GitHub Actions workflows. Its public docs emphasize runner hardware, cache acceleration, Docker cache, run/log history, monitors, metrics, test analytics, CI analytics, SSH debugging, CI tuning, and Autofix CI.
+
+Sources:
+
+- [Blacksmith documentation index](https://docs.blacksmith.sh/llms.txt)
+- [Blacksmith runner overview](https://docs.blacksmith.sh/blacksmith-runners/overview)
+
+## Product-space opportunity for Stackable
+
+Do **not** compete first on runner infrastructure. A sharper starting premise is a GitHub-native CI maintenance control plane that:
+
+1. Converts workflow and run data into an actionable pull-request health report.
+2. Keeps one canonical PR comment current rather than creating noisy comment streams.
+3. Helps teams create and repair workflows via an approval-first AI change process.
+4. Serves the same intelligence through a CLI designed for humans and coding agents.
+
+## Alternatives worth comparing later
+
+- Native GitHub Actions insights, workflow runs, checks, and PR status UI.
+- Blacksmith: observability, monitors, CI tuning, Autofix CI.
+- CI maintenance tools that offer workflow linting, flaky-test analytics, and policy controls.
+- AI configuration tools that generate GitHub Actions YAML but lack review, validation, or safe rollout.
+
+## Research limits
+
+This is a capability baseline, not a pricing or feature-parity claim. Validate API feasibility, GitHub App permissions, and GitHub comment/update behavior before committing an MVP architecture.

second-brain/sessions/2026-08-21-discovery.md

@@ -0,0 +1,33 @@
+# Session — 2026-08-21 Discovery
+
+## Completed
+
+- Ran and fully captured the requested `grill-me`, `find-skills`, `wayfinder`, and `interview-me` skill outputs.
+- Created this Obsidian-compatible second brain.
+- Searched current public Blacksmith materials and recorded a baseline in [[product/research-blacksmith]].
+- Confirmed the repository has no `Design.md` at the requested name during initial inspection.
+- Ran skill discovery queries for minimalist design, unslop writing, product marketing, code review, CI/CD GitHub Actions, and Emil Kowalski. The CLI returned no direct exact matches; raw outputs are preserved in [[skills/index]].
+
+## Interview record
+
+- **Initial audience:** small GitHub Actions teams plus individual developers/coding agents.
+- **MVP workflow answer:** “all” — the product owner considers PR health, AI workflow authoring, and organization CI management a connected product direction. The first public release must contain all three at useful initial depth.
+- **GitHub boundary:** GitHub.com only in v1.
+- **AI authority:** direct writes are required; organization administrators select writable branches.
+- **PR report:** use a Check Run and one canonical report, keeping the report last in the PR conversation; repost on material lifecycle changes or explicit refresh and edit minor state in place.
+- **Identity:** GitHub App + GitHub OAuth + CLI device/scoped-token login.
+- **Data boundary:** structured metadata and bounded failure excerpts, with full logs left in GitHub by default.
+- **Initial CI adapters:** GitHub Actions, CircleCI, and Buildkite.
+
+## Interface interview record
+
+- Three equal top-level workspaces: PRs, Organization, and AI Studio.
+- Keyboard image request was withdrawn.
+- AI Studio uses a staged Review Canvas with a deep, one-question-at-a-time requirements interview.
+- Validate generated workflows statically, then require an adversarial AI review against the directive; do not require preview runs.
+- Propose—not automatically apply—a revert after an applied change regresses.
+- The PR report must include next action, pipeline map, and health/risk information; its exact hierarchy is still open.
+
+## Next action
+
+Choose the report’s hierarchy so all three signals remain scannable rather than competing.