Phase 1: Parse Subcommand

Phase 1:

Parse Subcommand - Happycapy Skills Platform

What Is This Skill?

The “Phase 1: Parse Subcommand” skill, identified by tech-debt, is an initial parsing and command-detection layer for the Happycapy Skills platform. Its primary responsibility is to interpret the user's intent by analyzing the first positional argument provided to the skill. This argument specifies which operational mode the skill should execute. The available subcommands are scan, add, prioritize, and report. Without a valid subcommand, the skill provides a usage message and terminates with a failure verdict, ensuring that users always provide explicit instructions for technical debt management tasks.

This phase is foundational for the broader tech-debt skill, which is designed to track, categorize, and prioritize technical debt across a codebase. By enforcing strict subcommand parsing, this phase prevents ambiguous or accidental invocations that could lead to user confusion or unintended actions.

Why Use This Skill?

Technical debt is a critical challenge in any software project. Without systematic tracking and management, debt accumulates, causing code quality to degrade and maintenance costs to rise. The tech-debt skill addresses this by providing a structured workflow for identifying, registering, and handling technical debt.

The Parse Subcommand phase specifically adds value by:

• Ensuring that every invocation is intentional and explicit.
• Preventing accidental operations that might affect the debt register or trigger unnecessary scans.
• Providing clear feedback when required input is missing, thus improving user experience and operational safety.

By enforcing explicit command selection, this skill reduces the likelihood of mistakes and ensures that all technical debt operations are performed with clear intent.

How to Use It

The skill is invoked from the Happycapy command interface. Its argument-hint is [scan|add|prioritize|report], which means the first argument must be one of these subcommands. Below are the subcommands and their purposes:

• scan
  Scans the codebase for technical debt indicators, such as TODO, FIXME, and HACK comments, deprecated APIs, duplicated code, and other signals of debt.

• add
  Allows you to manually register a new item of technical debt. This is useful for cases not automatically detected by a scan.

• prioritize
  Triggers a reordering of the debt register, helping teams focus on the most critical issues first.

• report
  Generates a summary report about the current state of technical debt, offering visibility into existing problems.

Invocation Examples:

happycapy skills run tech-debt scan
happycapy skills run tech-debt add
happycapy skills run tech-debt prioritize
happycapy skills run tech-debt report

If no subcommand is provided:

happycapy skills run tech-debt

Output:

Usage: tech-debt [scan|add|prioritize|report]
Verdict: FAIL - missing required subcommand.

This output ensures that users are immediately aware of incorrect usage and can quickly correct their command.

When to Use It

Use the Parse Subcommand phase every time you interact with the tech-debt skill. It is always the entry point and is mandatory for any technical debt operation through this skill. This phase should be utilized:

• At the start of every technical debt-related operation in the Happycapy Skills platform.
• When you want to ensure that only valid, explicit commands are processed.
• As a safeguard against accidental or malformed invocations that could disrupt debt tracking workflows.

Important Notes

• Strict Input Requirements: The skill will not proceed unless a valid subcommand is provided. This reduces the risk of running incomplete or ambiguous commands.
• Clear Feedback: If invoked incorrectly, the skill provides a usage message and a failure verdict, making it easy for users to recover and retry.
• No Operational Side Effects: The Parse Subcommand phase only determines intent and mode. It does not modify the codebase or the debt register. Actual operations (such as scanning or adding debt) are delegated to later phases.
• Extensible Design: The parsing logic is designed to be easily extensible. If new subcommands are required in the future, they can be added with minimal impact on the parsing phase.

Example Parsing Code (Pseudocode)

def parse_subcommand(args):
    valid_subcommands = ['scan', 'add', 'prioritize', 'report']
    if not args or args[0] not in valid_subcommands:
        print("Usage: tech-debt [scan|add|prioritize|report]")
        print("Verdict: FAIL - missing required subcommand.")
        return False
    return args[0]

Summary:
The Phase 1: Parse Subcommand skill is a crucial foundational step in the technical debt management workflow on the Happycapy Skills platform. It ensures that every operation is explicit and intentional, setting the stage for robust, safe, and user-friendly debt tracking and remediation. Always begin your tech-debt workflow with a valid subcommand, and rely on this phase to prevent accidental actions and maintain clarity in your technical debt processes.