Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.agents/skills/plan-ticket/SKILL.md
T

7.1 KiB

name, description
name description
plan-ticket Create a complete implementation plan for a HiveGrid ticket from AGENTS.md, its ticket doc, linked planning sources, live Plane context, and current git state. Use when a user provides a HiveGrid ticket ID or asks to analyze, scope, sequence, or plan a ticket without implementing it yet.

Plan Ticket

Plan only. Do not edit code, ticket docs, Plane, or external systems. Stop after the plan and ask for approval before implementation.

1. Resolve the ticket

Require a ticket ID such as AK-P3. Then:

  1. Read AGENTS.md completely enough to apply the current rules relevant to the ticket.
  2. Read .planning/ticket-docs/README.md and .planning/ticket-docs/<TICKET-ID>.md completely. Stop if the ticket doc is missing.
  3. Follow only the granular sources linked by the ticket doc. Give .planning/ENTITY-MODEL.md priority where AGENTS.md requires it.
  4. Read the current branch, recent commits, and diff against origin/main to establish what is already implemented.
  5. Pull the live Plane ticket, comments, blocked-by, and blocks using .planning/plane-sync/fetch_ticket.py or the available Plane integration. If Plane is unavailable, continue from Git and the ticket doc but state that evidence gap.
  6. Never infer completion from a status badge alone.

2. Audit dependencies with three sources

Check both dependency directions. For every blocker or consumer, compare:

  1. Plane state and all relevant comments.
  2. Git/code reality, including merged commits and implementation notes.
  3. The blocker and dependent ticket docs.

Decide whether the exact contract needed by this ticket exists. When sources conflict, apply the precedence rules in AGENTS.md; otherwise expose the conflict instead of inventing a resolution. For cross-cutting contracts, schemas, shared services, or blocks consumers, include the dependent verification work in the plan.

3. Decide the delivery strategy

Classify every open item as:

  • selbst machbar
  • extern/blockiert
  • bewusst v2/out-of-scope

Recommend jetzt bauen, teilweise bauen, or zurückstellen, with a reason. Do not pull work forward from later tickets.

For UI-heavy work, read .planning/INTERIM-UI-PLAYBOOK.md and .planning/INTERIM-UI-DESIGN-STANDARDS.md. Missing final design does not automatically block the ticket: plan the AD-28 interim screen when the ticket permits it, and track final visual work as design-nachzug. Use finished Automation/Forms screens and existing Settings Subscription/Billing interim screens as style references.

If the ticket specifically integrates new or changed Subframe pages, also use $subframe-einbinden and incorporate its inventory and integration requirements.

4. Produce the plan in this order

  1. Plain-language introduction
  2. Current state and DoD percentage
  3. Dependencies and delivery strategy
  4. DoD-to-slices mapping
  5. Ordered build plan by slice
  6. Verification gates before commit
  7. Open questions and risks
  8. Reminder for post-build ticket-doc + Plane updates

5. Map every DoD item

For every DoD item, state:

  • Status: done, open, or blocked.
  • Fertigkeitskriterium: what must be true for full completion.
  • Proof: the code path, test, screen, external artifact, or Plane evidence that proves it.
  • Zählt NICHT als fertig: which partial implementation would be insufficient.
  • Slice: where the work and verification happen.

Cross-check each DoD item against Was wir bauen, Benötigte Screens, technical building blocks, Plane comments, and design notes. Count only fully satisfied points. Report % = completed DoD points / total DoD points, separating blocked work from work the developer can still do.

6. Make each slice executable

For each slice, name concrete files and include all applicable constraints:

  • Loader/action builds the view model; UI receives VMs and callbacks.
  • No @prisma/client or ~/db in packages/ui-app/**.
  • No direct packages/ui-subframe import from routes.
  • No useLoaderData inside packages/ui-app/**.
  • Reuse audit, activity, notifications, search, permissions, tenant scope, and other cross-cutting services from AGENTS.md.
  • Use i18n keys and the existing clear-text error/state patterns.
  • For UI, include interim/final visual state, smoke, hot-swap, and visual-baseline work as required.
  • For schema work, use a module schema, develop with prisma db push, and plan the current pre-merge migration/parity gates from docs/AGENT-CHECKLIST.md without guessing around AD-21 timing.

Call out central registries whenever a slice adds or changes their inputs:

  • Tenant-scoped Prisma model: tenant model registry plus ordering/tests.
  • Workspace package subpath export: explicit Vitest alias plus consumer suites.
  • Feature key: entitlements feature, blueprint, plan, and key-list tests.
  • Permission key: permission seed, defaults, scope display, and de/en strings.
  • Sidebar/navigation ID: UI registry, sidebar tests, and UI inventory mapping.
  • UI text: de/en translations and i18n gates.
  • Prisma schema: migration parity and the RLS live migration-chain gate.

7. Define verification before commit and push

Derive exact commands from docs/AGENT-CHECKLIST.md, the affected workspaces, and .gitea/workflows/ci.yml. Include:

  • typecheck, lint, and targeted tests for every affected package
  • existing consumer suites for shared files, not only new tests
  • applicable verify:* registry, i18n, RLS, migration, bundle, or Docker gates
  • seed idempotency and browser/staging proof when the ticket requires them
  • the no-US-provider and architectural anti-pattern checks when relevant

Do not schedule external writes, pushes, Plane changes, or Done transitions without explicit authorization.

8. Include the post-build audit reminder

Before any completion report or Done-state recommendation, perform a Ticket-Abschluss-Audit:

  1. Re-read the ticket doc and current Plane comments.
  2. Compare code state against every DoD item, required screen, and technical building block.
  3. Separate remaining work into selbst machbar, extern/blockiert, and bewusst v2.
  4. Count percentage only from fully satisfied DoD points. Partial backend-only or UI-only work does not count as a full DoD point.
  5. If a design ticket such as D-* is referenced, state whether its delta is integrated, replaced by a valid interim baseline, or still blocking.
  6. Update the ticket doc with date, proof, DoD checkboxes, and percentage before any Plane completion action.
  7. Mirror the result to Plane only with the required identity check and explicit authorization; set Done only at 100% DoD.
  8. If an interim screen was created, offer the optional David handover described in .planning/INTERIM-HANDOVER-GUIDE.md instead of creating it silently.

End the response after the plan and ask whether it should be approved or adjusted.

Mandatory constraints

  • Follow AGENTS.md strictly.
  • Stay in ticket scope.
  • Keep generated Subframe app chrome out of app screen components.
  • Mark out-of-scope ideas explicitly as 💡 Vorschlag (außerhalb Ticket-Scope): ....
  • If a source is ambiguous, stop and ask instead of inventing.