sdd-workflow

name	sdd-workflow
description	Use for rankingdepadel.club product/code work, active SDD specs, Codex planning, repository constraints, and deciding whether review or audit checkpoints apply.

SDD Workflow

Use this skill for product behavior, code changes, non-trivial planning, active specs, and repository constraints.

Repository Constraints

• Product: padel rankings, matches, player profiles, and Americano tournaments.
• Backend: Django. Frontend: Django templates and Bootstrap 5.
• Mobile: Capacitor WebView wrapper around the web product.
• Python: 3.10.12.
• Development DB: SQLite. Staging/production DB: Oracle Autonomous Database over TCPS.
• Use vanilla JavaScript only when necessary.
• DRF/API endpoints are deprecated and must not be extended.
• Backend owns business logic; templates render only.
• No frontend ranking logic.
• Reuse existing presentation classes/components before adding parallel styles.
• Treat user-edited UI text, labels, class names, and style choices as product intent. Do not normalize, rename, or "clean up" them while making adjacent changes unless the user explicitly asks.
• If a requested change touches user-written text or styles and the intended outcome is ambiguous, ask before editing that surface.
• For CSS/template fixes, trace the rendered template and actual selector or component path before editing styles; verify the selector changed is present on the affected surface.
• Before reusing a shared CSS class for a new component state, check whether later base selectors reset the same custom properties or declarations.
• When a shared state class must override a component base class, account for CSS cascade order with a colocated combined selector after the base selector.
• UI text is Spanish. Code, comments, docs, and specs are English.
• Apply DRY, KISS, SRP, YAGNI, and Explicit > Implicit.
• Avoid speculative refactors, renames, moves, and unrelated formatting.
• Verify current official behavior before relying on external tools, integration discovery, authentication, configuration paths, or versioned capabilities.
• Do not start runserver, frontend dev servers, or other local app servers unless the user explicitly asks. If manual UI verification would help, report the command instead.

SDD Gate

Before non-trivial implementation:

1. Check the current git branch.
2. If it is not develop, warn and wait for confirmation before editing.
3. Find or create the active approved non-release spec for the task under specs/###-short-title.md.
4. Start implementation only after the active-work spec is approved.

If the active-work spec is missing or incomplete, notify the user and wait for further instructions before proceeding.

Simple-change exception:

• Small, low-risk documentation, governance, or repository-guidance edits may skip a new active-work spec.
• Narrow bug fixes, focused tests, and small CSS/template corrections may skip a new active-work spec when scope and validation remain local.
• If the task grows beyond that narrow scope, return to the standard SDD gate.

Spec lifecycle:

• Active work uses non-release specs only.
• Specs created from $prd-to-specs follow the same active-work gate: implement only one approved non-release spec at a time unless the user explicitly widens scope.
• When implementation belongs to a PRD-backed plan in docs/prds/, use the PRD's Approved Spec Breakdown to choose the next spec:
  • select the first approved, non-implemented spec whose dependencies or blockers are satisfied;
  • if the next spec is HITL or has unresolved blockers, report that and wait;
  • do not choose by highest filename number alone.
• If multiple PRDs could own the task, ask the user to choose the PRD before selecting an implementation spec.
• specs/release-*.md files are historical release records.
• Loose non-release specs use Status: approved|implemented and Release tag: unreleased.
• Move a spec to implemented only when the scoped work is complete and the development cycle is being closed.
• After every implementation, propose 3-6 concise manual functional checks covering the changed user-facing or operational behavior.

Planning Behavior

• In planning workflows, verify and report the branch, but wait only before implementation or file edits when it is not develop.
• Explore targeted repo context before asking questions; avoid broad discovery when the needed facts are local to a few files or specs.
• Ask preference-locking questions for non-trivial work when product, UX, or implementation tradeoffs remain.
• Markdown remains the default planning and spec format. Static HTML may be suggested when it helps the user choose between alternatives, especially different UI/UX display options, mockups, diagrams, comparison panels, collapsible sections, filtering, toggling, or navigation aids.
• When using HTML planning artifacts, state whether the HTML replaces a Markdown artifact or complements it. Keep artifacts static, reviewable, maintainable, suitable for Git diffs, and limited to planning/review scope.
• HTML planning artifacts may use Bootstrap via CDN and small JavaScript for review interaction. Do not treat CDN or JavaScript choices in planning artifacts as implementation assumptions.
• Write proposal and review artifact chrome in English. User-facing UI copy inside mockups or UX examples may stay in Spanish when it represents product text.
• Internal workflow content stays English; user-facing UI copy shown in mockups or UX examples stays Spanish.
• Use GitHub Issues as backlog and pre-spec intake. Issues may be rough ideas, free-form notes, screenshots, or detailed ChatGPT-generated pre-specs.
• ChatGPT pre-specs are starting points for Codex planning, not active specs.
• Formal approved implementation specs live under specs/.
• When work starts from a GitHub Issue, use the Issue as request context and route through the appropriate task skill; keep branch, spec, validation, and release gates unchanged.
• Active specs should capture only scope, constraints, stable execution notes, acceptance checks, and validation needed to execute safely.
• Validation commands in specs must be runnable from repo root. Use python paddle/manage.py for Django management commands; pass Django test labels as apps, packages, or dotted modules, not file paths. Use pytest for pytest-style file targets such as frontend, Americano, JavaScript, or release-orchestrator tests.
• Do not require active specs for planning interviews, PRDs, issue triage, pre-specs, audits, or decision-only work.

Quality Checkpoints

Evaluate the relevant checkpoint before advancing non-trivial work:

• /review: fast targeted review of a draft, diff, or scoped change set.
• $audit: Django view behavior, architecture, security, reuse, and ORM performance.
• $template-presentation-audit: one-template CSS cascade, computed-style, and responsive presentation review.
• $governance-markdown-auditor: governance markdown, ownership, duplication, and process overhead.

If no checkpoint fits, say why. Surface only medium/high-severity findings. Ask the user whether to address or discard each finding before fixing it.

Model and Schema Changes

When Django model/schema changes are introduced, generate and apply migrations in development before treating the task as complete.

For schema changes that add fields, defaults, timestamps, status flags, or permission gates, ask the user how existing rows should behave after the migration before implementation. Add a data migration or regression check when that legacy-row behavior differs from the field default for newly created rows.