Skill for completing tech breakdowns

[trmartin4]

📔 Objective

Adds the next in a sequence of changes to decompose and enhance the existing writing-tech-breakdowns skill, for use with our new tech-breakdowns repo.

• Creating a new breakdown Breakdown initialization and spec definition skills #141
• Defining the Specification (the WHAT and WHY) Breakdown initialization and spec definition skills #141
• Defining the Plan (the HOW) Breakdown plan skill #143
• Defining the Tasks Breakdown tasks skill #144
• Completing the breakdown (this PR)

[github-actions]

Plugin Validation Summary — bitwarden-delivery-tools

Result: ✅ PASS — All required validations succeed. No critical or major issues. A few minor cleanups are recommended but none block the PR.

Validated changed files:

• plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json
• plugins/bitwarden-delivery-tools/CHANGELOG.md
• plugins/bitwarden-delivery-tools/README.md
• plugins/bitwarden-delivery-tools/skills/completing-breakdown/SKILL.md

---

1. Plugin Validation (plugin-validator)

PASS. Manifest, structure, version consistency, and changelog are all correct.

Check	Result
plugin.json valid JSON, name/version/required fields	✅ bitwarden-delivery-tools, 2.1.0, valid semver
Version consistency (plugin.json ↔ marketplace.json)	✅ both 2.1.0, descriptions match verbatim
CHANGELOG has [2.1.0] entry in Keep a Changelog format	✅ CHANGELOG.md:8 documents the new skill
Directory/auto-discovery layout skills/<name>/SKILL.md	✅ matches frontmatter name
README documents the new skill	✅ README.md:34 (Technical design table)
No hardcoded credentials	✅ none found

2. Skill Review (skill-reviewer) — completing-breakdown

PASS (with minor cleanups). Frontmatter well-formed; description is strong (third-person, six explicit trigger phrases, ~330 chars). Body is ~707 words — below the 1,000–3,000 target but appropriate for this narrow, single-file procedural task, so progressive disclosure is not warranted. Writing style is consistently imperative. No broken file references (skill references no external files).

3. Security Validation (reviewing-claude-config)

PASS. No committed secrets, no hardcoded credentials, no settings.local.json in the changeset.

• allowed-tools scoping (SKILL.md:6): narrowly scoped — Read, Edit, Glob, Bash(git mv:*), Bash(git status:*), Bash(mkdir:*), AskUserQuestion. No blanket Bash. ✅
• Path-injection defense: The path-interpolating commands (git mv, mkdir) are backed by explicit input validation — slug/Jira-key regex allowlists, .. and out-of-tree path rejection, and mandatory single-quoting of interpolated operands (SKILL.md:43, :60, :61). Positive security practice. ✅

---

Findings

Critical (must fix): 0

None.

Major (must fix): 0

None.

Minor (should fix)

1. SKILL.md:76 — Orphan closing tag. The Output section opens as a Markdown heading ## Output (line 69) but the body ends with a stray </output> tag that has no matching opener (copy/paste artifact). Fix: delete the </output> on line 76. (The <HARD-GATE>/</HARD-GATE> pair at lines 15/23 is correctly balanced.)

2. SKILL.md:30 — Typos in a Key Principle heading. "Inform the use after move is complete." should read "Inform the user after the move is complete." Fix: use → user (and add "the"). User-facing guidance text.

3. SKILL.md:4-5 — Non-standard frontmatter keys (argument-hint, arguments). Only name and description are required/standard for skills; argument-hint/arguments are command-oriented fields and may be inert in a skill context. The body relies on $breakdown (line 16), so verify that arguments: breakdown actually populates $breakdown at activation — if it does not, the HARD-GATE's "If $breakdown was provided" branch is dead logic. Note: this matches the existing convention across 5 sibling skills in this plugin, so it is not a regression introduced by this PR. No action required for merge; noted for consistency awareness.

4. CHANGELOG.md:8 — Date confirmation. The [2.1.0] entry is dated 2026-06-19, identical to the [2.0.0] entry below it. Same-day releases are legal; just confirm the date is intended (repo context date is 2026-07-01).

5. SKILL.md:21 — Undefined term. The skill repeatedly references "the tech-breakdowns checkout / working copy" (lines 21, 36, 43, 61) without establishing where it is. A one-line note in the Overview clarifying that breakdowns live in a separate bitwarden/tech-breakdowns working copy would help the skill stand alone. Minor.

---

Positive Highlights

• Excellent security hygiene in the new skill: explicit path-traversal rejection, slug/Jira-key regex validation, and shell-metacharacter-safe single-quoting before any git mv / mkdir.
• allowed-tools uses narrow, scoped Bash(...) permissions rather than blanket Bash.
• Version bump, changelog entry, marketplace entry, and README documentation are all present and consistent — fully satisfies the repo's plugin-change requirements.
• Correct ordering rationale ("Status flip then move") and history preservation via git mv are documented with their failure modes.

Overall: safe to merge. The recommended fixes (orphan tag, typo) are cosmetic.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

Reviewed the new completing-breakdown skill added to bitwarden-delivery-tools, along with the accompanying version bump (2.0.0 → 2.1.0), changelog entry, and README/marketplace updates. The skill guides retiring a shipped Tech Breakdown by flipping its status to Complete and git mv-ing the folder into the team's complete/ archive.

The prior review's security concern (unquoted/unvalidated path interpolation into mkdir/git mv, CWE-78/CWE-22) is resolved in the current revision: Phase 1 now carries the full validation block — slug and Jira-key regexes, .. rejection, character allowlist, and working-copy containment — matching the starting-breakdown sibling convention, and Phase 3 single-quotes every interpolated operand. The earlier "surface before vs. after the move" ordering contradiction is also reconciled (Key Principles and Phase 3 now consistently say "after"). Version bumps are consistent across plugin.json, marketplace.json, and README.md, and the changelog follows Keep a Changelog format.

Code Review Details

No findings meet the reporting threshold. Previously raised concerns from existing review threads have been addressed in the current revision.

[theMickster]

Suggested adjustments to the skill are posted. No longer a codeowner; so they're just suggestions now. Lemme know if you need any follow-up help.