edercnj/x-create-bug

Skill: Create Bug Report (slim — ADR-0012)

Create a new bug report from the standard template with automatic slug generation, status initialization, and structured metadata.

Triggers

• /x-create-bug "Login form crashes on invalid email" — create bug with description only
• /x-create-bug "Login form crashes on invalid email" --severity HIGH — create with severity
• /x-create-bug "Login form crashes on invalid email" --scope single-file --severity HIGH — full invocation
• /x-create-bug "Session token leaks to browser console" --severity CRITICAL — security bug

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | description | String | Yes | — | Bug description (8–200 characters) | | --severity | Enum | No | MEDIUM | One of: LOW, MEDIUM, HIGH, CRITICAL | | --scope | Enum | No | single-module | One of: single-file, single-module, cross-module (vocabulário de scope de bug do knowledge bug-lifecycle; não confundir com o scope de implementação de story SIMPLE/STANDARD/COMPLEX) | | --id | String | No | auto | Auto-generated as 6-digit integer (bug-NNNNNN); override if needed |

Output Contract

On success, the skill creates:

1. Bug directory: .aikittools/bugs/bug-NNNNNN/ with bug.md, story files, and IMPLEMENTATION-MAP.md
2. Bug file: .aikittools/bugs/bug-NNNNNN/bug.md with complete template and metadata
3. Story files: story-01-regression-test.md, story-02-fix.md (+ more per severity/scope rules)
4. Implementation map: IMPLEMENTATION-MAP.md aggregating stories with dependency graph
5. Status field: **Status:** Pendente (initial state)
6. Metadata: YAML frontmatter + all 9 RA9 sections with defaults

Returns JSON to stdout:

{
  "bugId": "bug-000001",
  "slug": "login-form-crashes-on-invalid-email",
  "bugFile": ".aikittools/bugs/bug-000001/bug.md",
  "severity": "HIGH",
  "scope": "single-module",
  "status": "Pendente",
  "created": "2026-05-07T14:23:15Z",
  "stories": {
    "created": [
      ".aikittools/bugs/bug-000001/story-01-regression-test.md",
      ".aikittools/bugs/bug-000001/story-02-fix.md"
    ],
    "idempotent": false,
    "wallClockMs": 87
  },
  "implementationMap": {
    "mapPath": ".aikittools/bugs/bug-000001/IMPLEMENTATION-MAP.md",
    "storiesAggregated": 2,
    "elapsedMs": 95
  }
}

When decomposition or map generation fails, the fields are replaced by warning entries:

{
  "stories": null,
  "storiesError": { "exitCode": 5, "message": "PARSE_ERROR: cannot extract severity" },
  "implementationMap": null
}

Workflow Overview

1.  PARSE_VALIDATE -> Validate description (8–200 chars), severity enum, scope enum
2.  SLUG           -> NFKD normalize + strip non-alphanumeric + lowercase + collapse hyphens + truncate-40
3.  ASSIGN_ID      -> Auto-detect MAX(existing bug-NNNNNN) + 1 (6-digit), or validate user-provided --id
4.  CREATE_DIR     -> mkdir -p .aikittools/bugs/<bug-id>/
5.  LOAD_TEMPLATE  -> Read src/templates/_TEMPLATE-BUG.md (abort on missing)
6.  INSTANTIATE    -> sed-substitute {{BUG_DESCRIPTION}}/{{BUG_ID}}/{{SLUG}}/{{SEVERITY}}/{{SCOPE}}/...
7.  WRITE          -> Write to .aikittools/bugs/<bug-id>/bug.md + git commit scaffold
8.  DECOMPOSE      -> Decompose bug.md into 2–4 story files inline (non-fatal: log warning on failure)
9.  MAP            -> Generate IMPLEMENTATION-MAP.md inline (non-fatal: only if Step 8 created stories)
10. EMIT           -> jq response envelope (bugId, slug, bugFile, severity, scope, status, created, stories, implementationMap)

Detailed bash for each step, slug-generation pipeline, template substitution map, and worked examples in references/full-protocol.md:

• Step 1 (§Step 1): full validation bash with exit-code-1 on each guard. --output parameter removed; path is always .aikittools/bugs/<bug-id>/bug.md.
• Step 2 (§Step 2): iconv + sed + tr slug-generation pipeline; 40-char truncation.
• Step 3 (§Step 3): auto-increment from ls .aikittools/bugs/ + sort -n | tail -1; ^bug-[0-9]{6}$ regex for user-provided IDs.
• Step 4 (§Step 4): mkdir -p .aikittools/bugs/<bug-id>/; abort on write failure.
• Step 5 (§Step 5): template path src/templates/_TEMPLATE-BUG.md; abort on missing.
• Step 6 (§Step 6): 10-substitution map ({{BUG_DESCRIPTION}}, {{BUG_ID}}, {{SLUG}}, {{SEVERITY}}, {{SCOPE}}, {{PERSONA}}, {{VERSION_OR_SHA}}, {{OS_RUNTIME}}, {{JAVA_VERSION}}, {{DATE}}).
• Step 7 (§Step 7): atomic write to .aikittools/bugs/<bug-id>/bug.md + Pendente initialization + git commit scaffold.
• Step 8 (§Bug Decomposition Procedure): execute o procedimento de decomposição inline (D1–D6); capture o envelope como DECOMPOSE_RESULT; on non-zero exit, set STORIES_ERROR and continue.
• Step 9 (§Implementation Map Procedure): execute o procedimento de mapa inline (M1–M7); capture o envelope como MAP_RESULT; on non-zero exit, set MAP_ERROR and continue (only runs if Step 8 created stories).
• Step 10 (§Step 10): jq -n envelope construction with stories and implementationMap fields (or error fields on failure).
• Worked Examples (§Examples): 3 end-to-end invocations with JSON outputs.

Error Handling

| Scenario | Exit Code | Message | |----------|-----------|---------| | Description too short (< 8 chars) | 1 | "Description must be 8–200 characters" | | Description too long (> 200 chars) | 1 | "Description must be 8–200 characters" | | Invalid severity | 1 | "Severity must be LOW|MEDIUM|HIGH|CRITICAL" | | Invalid scope | 1 | "Scope must be single-file|single-module|cross-module" | | Template not found | 1 | "Template not found: {path}" | | Slug generation failed | 1 | "Slug generation failed (no alphanumeric content)" | | Invalid user-provided ID | 1 | "Bug ID must match pattern bug-NNNNNN" | | Directory creation failed | 1 | "Failed to create bug directory: {path}" | | File write failed | 1 | "Failed to write bug file: {path}" | | Decomposition failed | WARNING (non-fatal) | Logged to stderr; storiesError field added to envelope | | Map generation failed | WARNING (non-fatal) | Logged to stderr; mapError field added to envelope | | jq not available | 127 | "jq is required" |

Performance Contract

Target: < 500 ms for slug generation + file creation. No network I/O; all operations are local file and string processing.

Knowledge Pack References

Read src/knowledge/shared/governance-baselines/bug-lifecycle/knowledge.md for the canonical bug lifecycle state machine.

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | Bug Decomposition (Step 8) | inlined | Decomposição em story files; protocolo D1–D6 em references/full-protocol.md | | Implementation Map (Step 9) | inlined | Geração do IMPLEMENTATION-MAP.md; protocolo M1–M7 em references/full-protocol.md | | x-refine-bug | called after | Refine workflow accepts created bugs and their stories | | _TEMPLATE-BUG.md | dependency | Template must exist at src/templates/_TEMPLATE-BUG.md | | bug-lifecycle.yaml | dependency | Capability declaration must be present |

References

• Capability: config/capabilities/bug-lifecycle.yaml
• Template: src/templates/_TEMPLATE-BUG.md
• Refinement: /x-refine-bug
• story-0080-0001, story-0080-0002, story-0080-0003, task-0080-0001-003

Full Protocol

Minimum viable contract above. Detailed bash for all steps (incluindo os procedimentos inline de decomposição D1–D6 e de mapa M1–M7), slug-generation pipeline, template substitution map, worked examples, and acceptance test scenarios live in references/full-protocol.md per ADR-0012 (skill body slim-by-default).