terrylica/cc-skills

implement-plan-preflight

Run the Preflight phase of the ITP workflow to create ADR and design spec artifacts.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/terrylica/cc-skills --skill implement-plan-preflight

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Implement Plan Preflight

Execute the Preflight phase of the /itp:go workflow. Creates ADR and Design Spec artifacts with proper cross-linking and verification.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

  • Invoked by /itp:go command during Preflight phase
  • User asks to create an ADR for a feature
  • User mentions "design spec" or "MADR format"
  • Manual preflight verification needed

Preflight Workflow Overview

P.1: Create Feature Branch (if -b flag)
         │
         ▼
P.2: Create ADR File (MADR 4.0)
         │
         ▼
P.3: Create Design Spec (from global plan)
         │
         ▼
P.4: Verify Checkpoint (MANDATORY)

CRITICAL: Do NOT proceed to Phase 1 implementation until ALL preflight steps are complete and verified.


Quick Reference

ADR ID Format

YYYY-MM-DD-slug

Example: 2025-12-01-clickhouse-aws-ohlcv-ingestion

File Locations

ArtifactPath
ADR/docs/adr/$ADR_ID.md
Design Spec/docs/design/$ADR_ID/spec.md
Global Plan~/.claude/plans/<adj-verb-noun>.md

Cross-Links (MANDATORY)

In ADR header:

markdown
**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

In spec.md header:

markdown
**ADR**: [Feature Name ADR](/docs/adr/YYYY-MM-DD-slug.md)

Execution Steps

Step P.1: Create Feature Branch (Optional)

Only if -b flag specified. See Workflow Steps for details.

Step P.2: Create ADR File

  1. Create /docs/adr/$ADR_ID.md
  2. Use template from ADR Template
  3. Populate frontmatter from session context
  4. Select perspectives from Perspectives Taxonomy

Step P.3: Create Design Spec

  1. Create folder: mkdir -p docs/design/$ADR_ID
  2. Copy global plan: cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md
  3. Add ADR backlink to spec header

Step P.4: Verify Checkpoint

Run validator or manual checklist:

bash
uv run scripts/preflight_validator.py $ADR_ID

Checklist (ALL must be true):

  • [ ] ADR file exists at /docs/adr/$ADR_ID.md
  • [ ] ADR has YAML frontmatter with all 7 required fields
  • [ ] ADR has **Design Spec**: link in header
  • [ ] DIAGRAM CHECK 1: ADR has Before/After diagram (Context section)
  • [ ] DIAGRAM CHECK 2: ADR has Architecture diagram (Architecture section)
  • [ ] Design spec exists at /docs/design/$ADR_ID/spec.md
  • [ ] Design spec has **ADR**: backlink in header

If any item is missing: Create it now. Do NOT proceed to Phase 1.


YAML Frontmatter Quick Reference

yaml
---
status: proposed
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-1, Agent-2]
research-method: single-agent
clarification-iterations: N
perspectives: [Perspective1, Perspective2]
---

See ADR Template for full field descriptions.


Diagram Requirements (2 DIAGRAMS REQUIRED)

⛔ MANDATORY: Every ADR must include EXACTLY 2 diagrams:

DiagramLocationPurpose
Before/AfterContext sectionShows system state change
ArchitectureArchitecture sectionShows component relationships

BLOCKING GATE: Do NOT proceed to design spec until BOTH diagrams are embedded in ADR.


Reference Documentation


Validation Script

bash
# Verify preflight artifacts
uv run scripts/preflight_validator.py <adr-id>

# Example
uv run scripts/preflight_validator.py 2025-12-01-my-feature

Troubleshooting

IssueCauseSolution
Validator failsMissing ADR or specCreate both files before running validator
Frontmatter invalidMissing required fieldsCheck all 7 ADR fields and 5 spec fields
Spec phase mismatchWrong phase valueUse: preflight, phase-1, phase-2, or phase-3
ADR status wrongManual status editLet workflow manage status transitions
Design folder missingWrong path structureUse docs/design/YYYY-MM-DD-slug/spec.md

Post-Execution Reflection

After this skill completes, check before closing:

  1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
  2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
  3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

aus demselben Repository

Weitere Skills

Alle Skills
terrylica
Community

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.