uberblick

Category: Tools & Productivity | Uploader: uberblick-ai | Downloads: 0 | Version: v1.0（Latest）
Run $uberblick as a guided MCP workflow using workflow_hints and role-agent playbooks for PRDs, RFCs, and implementation review
Changelog: Source: GitHub https://github.com/uberblick-ai/skills
Directory Structure

Current level: plugins/uberblick/codex/
📁 agents/
- 📄 docs-integrity-checker.md 1.0 KB
- 📄 implementation-reviewer.md 590 B
- 📄 openai.yaml 240 B
- 📄 prd-critic.md 2.9 KB
- 📄 rfc-architect.md 2.7 KB
📄 SKILL.md 10.5 KB
SKILL.md

---
name: uberblick
description: Run $uberblick as a guided MCP workflow using workflow_hints and role-agent playbooks for PRDs, RFCs, and implementation review
---

You are starting an Uberblick working session. Follow these steps exactly:

## Step 0 — Check for a direct page ID
If `$ARGUMENTS` looks like a UUID (e.g. `019c93b0-72eb-71a1-8cdf-c8c6803a9056`), skip Steps 1–3 and go directly to Step 4, using that UUID as the page `id`.

## Step 0.5 — Route bug intake directly when appropriate
If the user's request, or a newly discovered issue during the session, is primarily about broken behavior now, a regression, or triage intake rather than planning/execution work:

1. Fetch `uberblick://docs/bug-guide`.
2. Use `list_bugs` to check for existing similar bugs.
3. Use `create_bug_tool` when a new bug is the right artifact.
4. If bug filing fully resolves the request, stop. Otherwise continue and link the bug from the related PRD/RFC instead of turning the planning record into a bug report.

## Step 1 — List workspaces
Call the `list_workspaces` MCP tool to get all workspaces.

## Step 2 — Fetch active planning records
For each workspace returned:

1. Call `list_prds` with that `workspace_id`.
2. Call `list_rfcs` with that `workspace_id`.

Collect all records where `parent_status` is `"to_do"` or `"in_progress"` (exclude `"complete"`).

If `$ARGUMENTS` was provided (and is not a UUID), filter further to records whose title contains the argument (case-insensitive).

If no active records exist, tell the user and stop.

## Step 3 — Let the user pick
Present the records as options.
Format each option as: `[type][status_name] Title` (e.g. `[PRD][Draft] Auth Revamp`).
Group by workspace name if there are multiple workspaces.
Limit to 4 options per question; if more exist, ask the user to provide a keyword to narrow down.

## Step 4 — Load context and workflow contracts
Once the user picks a PRD or RFC:

1. Call `get_page` with the selected record `id`.
2. Call `get_resource` for:
   - `uberblick://docs/workflow`
   - `uberblick://docs/workflow-roles`
3. Call `get_linked_pages` with `id: "prd:<uuid>"` or `id: "rfc:<uuid>"` depending on record type.
4. For each linked PRD/RFC, call `get_page` to load context.
5. Read `workflow_hints` from the selected record response and store:
   - `stage`
   - `role_sequence`
   - `active_role` (present for RFCs and in-progress PRDs)
   - `active_role_instruction` (present when `active_role` is set)
   - `next_role` (present for Draft PRDs in `to_do` status — offer-only, do not auto-run)
   - `confirmation_required`
   - `pending_completion_checks`

## Step 5 — Brief the user
Present a concise briefing:
- **Selected record title/type/status**
- **Current stage** from `workflow_hints.stage`
- **Active role** from `workflow_hints.active_role` (or available role from `workflow_hints.next_role.role` if `active_role` is absent)
- **Linked records** (titles + status)
- **Pending completion checks** from `workflow_hints.pending_completion_checks`

## Step 6 — Run the active role
If `workflow_hints.next_role` is present and `workflow_hints.active_role` is absent (Draft PRD):
- Inform the user that `next_role.role` is available (e.g. "prd-critic is available — want me to run a critique pass?").
- Do not auto-run the role. Wait for user confirmation.
- If the user confirms, run the role using `next_role.role` and `next_role.description` as the instruction.

Otherwise, map `workflow_hints.active_role` to a local role definition file:

- `prd-critic` -> `./agents/prd-critic.md`
- `rfc-architect` -> `./agents/rfc-architect.md`
- `implementation-reviewer` -> `./agents/implementation-reviewer.md`
- `docs-integrity-checker` -> `./agents/docs-integrity-checker.md`

Path resolution rule: resolve `./agents/...` relative to this `SKILL.md` file's directory (the skill folder), not the repository root.

Execute the active role using:

1. the selected record content,
2. linked PRD/RFC context,
3. `workflow_hints.active_role_instruction`,
4. the role file's output contract.
5. Enforce artifact boundary:
   - PRD findings must stay at product-requirement level.
   - Technical/design specifics must be output only as `RFC Remarks` (brief reminders). Keep this high-level only: technical and implementation details do not belong in the PRD.
6. Enforce decision-source boundary:
   - Keep unresolved product decisions in `gaps_and_ambiguities` only (single source of truth).
   - In persisted PRD content, render this section header as `Gaps and ambiguities` (human-readable). The underscore form is identifier-only.
   - Do not create a second action list that repeats the same items with different wording.
   - PM/owner decisions should be captured as comments/discussion on those gaps.
7. If active role is `rfc-architect` and unresolved PRD decisions remain:
   - present option paths directly in the live LLM session for PM selection,
   - do not write those option menus into PRD body content.

If the role file is missing, continue using `workflow_hints.active_role_instruction` plus `uberblick://docs/workflow-roles`.

## Step 7 — Write outputs through MCP tools
Never treat local role output as final state until it is written through MCP.

- Use `update_prd_tool` for PRD records.
- Use `update_rfc_tool` for RFC records.

When relevant, include:

- content updates,
- status updates,
- `completion_gate_update` for `page_sync_handoff` / `docs_drift_audit`.

Follow the active role's agent file output contract for content structure and decision-handling rules.

Page Impact rule for PRD writes:

- If touching `## Page Impact`, keep every entry in validator-compatible checklist form from `uberblick://docs/markdown-spec`.
- Actionable entries must contain `[Title](page:UUID)` or `uberblick://docs/...`; if none apply, use exactly one checked no-update line.
- Before setting completion checks to `acknowledged`, ensure every actionable entry is checked.

Active comment-anchor migration rule:

- When rewriting/removing text that contains active `{comment:thread_uuid}...{/comment:thread_uuid}` markers, reposition each marker onto the new decision/result sentence in the updated content.
- Never drop an active marker during `update_prd_tool` / `update_rfc_tool` writes.
- If no equivalent sentence exists, add a short `Decision:` (or `Resolution:`) line and attach the marker there before submitting.

After each write, do not auto-refetch with `get_page`. Re-fetch only when required:

- verifying final status / completion-gate outcomes,
- recovering from ambiguous update errors, or
- reading fields not returned by the update response.

## Step 8 — Handle blocked transitions
If a status move to complete is blocked:

1. parse `missing_checks` and `required_sequence` from the error payload,
2. run the missing role/workflow action directly,
3. retry with one `update_prd_tool` / `update_rfc_tool` call that includes:
   - target `status_id`,
   - `completion_gate_update` for all resolved checks,
4. fetch `guidance_resources` only if the payload is unclear/contradictory,
5. verify via `get_page` only for touched records involved in the retry.

Do not set `acknowledged` before the corresponding action is complete.
Do not move one linked PRD/RFC to `Done` while another linked record is still blocked.

## Step 9 — Start implementation work (developer session)
When coding is in scope:

1. ALWAYS work in a branch.
2. Follow repository instructions (`docs/instructions/`).
3. Before the first code edit, enforce execution-entry status:
   - if current `parent_status` is not `"in_progress"`:
     - call `list_statuses` with `parent: "in_progress"`,
     - choose the most appropriate in-progress status for execution start (prefer exact name `In Progress`; otherwise the closest equivalent),
     - call `update_prd_tool` or `update_rfc_tool` with that `status_id`.
4. If status transition fails, stop implementation work and report the blocker; do not write code changes until resolved.
5. Keep linked PRD/RFC records intentionally in sync.

## Step 10 — Open PR Early (Draft) and Push Incrementally

Do this shortly after the first meaningful implementation commit.

1. Push the branch and open a **draft** PR (title from PRD; body includes PRD UUID + short summary).
2. Keep pushing incremental commits throughout implementation.
3. Keep the PR in draft until implementation and validation are complete.
4. If draft PR creation fails, report the blocker and retry after the next push.

## Step 11 — Wrap up: status, review handoff, and docs

Do this when implementation is complete.

1. Determine intended handoff status:
   - if PR is open: use the highest `in_progress` status (typically `In Review`),
   - if PR is merged: use the default complete status (typically `Done`).
2. If PR is draft, mark it ready for review.
3. If PR is open, request Copilot review by adding reviewer `app/github-copilot`. If this fails, note the error and continue.
4. Audit only likely-drift docs:
   - target explicitly touched docs + PRD `Page Impact` targets,
   - fetch those pages in parallel,
   - update only pages with stale facts.
5. Status sync in one pass (parallel where safe):
   - list every touched PRD/RFC,
   - call one `update_prd_tool` / `update_rfc_tool` per record with final `status_id`,
   - when moving to complete, include `completion_gate_update` in that same call,
   - if any status update fails, stop and fix before continuing.
6. Verification gate (required):
   - call `get_page` once per touched PRD/RFC after status updates,
   - verify each record is in intended handoff status,
   - verify linked PRD/RFC statuses are intentionally aligned (no accidental mixed final states).
7. Report a final status summary in the handoff message:
   - `record_id`
   - `record_type` (`prd`/`rfc`)
   - `final_status_name`

## Step 12 — Monitor CI and PR comments

Run this step only while the PR is open. If the PR is already merged, skip to Step 13.

1. Periodically check PR status (`gh pr checks`) and comments (`gh pr view --comments`).
2. If CI is failing, inspect failed logs (`gh run view --log-failed`), fix issues, commit, and push.
3. For PR comments:
   - fix actionable correctness/standards issues and reply on the PR
   - leave purely stylistic/opinion comments for human judgment
4. Continue until CI is green and no actionable comments remain.

## Step 13 — Claude/Codex parity check
Before final signoff, ensure this session did not violate policy parity:

- gate behavior and `completion_gate_update` rules match MCP responses,
- `workflow_hints` stage/role sequence was respected,
- manual web UI status remains authoritative and is not auto-reverted.

Report the final PR URL to the user.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
uberblick

Directory Structure

SKILL.md

Report

Notice
