Phase 0: Parse Arguments

Phase 0:

Parse Arguments

What Is This?

Phase 0: Parse Arguments is the initial skill phase for the milestone-review skill on the Happycapy Skills platform. Its purpose is to extract, validate, and resolve user-provided arguments that specify which milestone to review and which review mode to apply. This phase ensures that downstream processes in the milestone review pipeline have precise configuration and context, sourced from command-line inputs, persistent configuration files, or sensible defaults.

The milestone-review skill itself generates a comprehensive progress review for a given project milestone, evaluating feature completeness, quality metrics, risk assessment, and providing a go/no-go recommendation. Phase 0 establishes the milestone target and the level of review detail (full, lean, or solo) before any data gathering or analysis occurs.

Why Use It?

Parsing arguments upfront is critical for several reasons:

• Consistency: Ensures that every review invocation begins with clear, reproducible inputs, reducing ambiguity and errors in milestone selection or review mode.
• Flexibility: Allows users to override defaults for specific runs, supporting both one-off reviews and persistent team preferences.
• Automation: Enables seamless integration with scripts, CI/CD tools, or Director Gates, as described in the .claude/docs/director-gates.md documentation.
• User Experience: Provides clear, immediate feedback if arguments are missing or invalid, minimizing confusion and manual troubleshooting.

Without this phase, subsequent review logic may operate on the wrong milestone or with inappropriate review criteria, compromising the accuracy and utility of the generated reports.

How to Use It

The argument parsing process follows a strict, layered resolution pattern:

1. User-Provided Arguments:
   The user can explicitly specify both the milestone and the review mode.

   • Syntax:
     plaintext

     milestone-review [milestone-name|current] [--review full|lean|solo]

     • milestone-name can be any valid milestone (e.g., alpha, beta, v1.0) or the keyword current to select the most recent.
     • --review is an optional flag to set the review mode.

   Example:

   plaintext

   milestone-review current --review full

2. Fallback to Persistent Configuration:
   If the --review flag is omitted, the skill attempts to read the default review mode from:

   plaintext

   production/review-mode.txt

   The file should contain one of the allowed modes (full, lean, solo).

3. Default Behavior:
   If neither the --review flag nor the configuration file is present, the review mode defaults to lean.

4. Parsing Logic (Pseudocode):

   python

   import sys
   import os
   
   def parse_args(argv):
       milestone = 'current'
       review_mode = None
   
       # Parse positional and optional arguments
       for i, arg in enumerate(argv[1:]):
           if arg.startswith('--review'):
               if i + 2 < len(argv):
                   review_mode = argv[i + 2]
           elif not arg.startswith('-'):
               milestone = arg
       
       # Fallback to config file if needed
       if not review_mode:
           try:
               with open('production/review-mode.txt', 'r') as f:
                   review_mode = f.read().strip()
           except FileNotFoundError:
               review_mode = 'lean'
       
       return milestone, review_mode

This phase should only be run once per parent process, and its resolved arguments should be stored and reused for all subsequent gate spawns within that session.

When to Use It

• Milestone Checkpoints:
  Run at each major milestone checkpoint to ensure the review context is accurate.
• Milestone Deadline Evaluations:
  Use when evaluating readiness for an upcoming milestone or release deadline.
• Automated Review Pipelines:
  Integrate into automated scripts or CI/CD workflows where milestone and review mode need to be set programmatically.
• Director Gate Spawns:
  Use in tandem with Director Gates to ensure all spawned reviews in a session use the same resolved parameters.

Important Notes

• Strict Argument Pattern:
  Only milestone-name|current and --review full|lean|solo are recognized. Extra or malformed arguments should trigger an error or prompt.
• Resolution Order:
  Always prioritize explicit command-line input, then persistent configuration, then defaults. This ensures user intent is respected.
• Single-Run Scope:
  The resolved values should be cached and reused for the entire run to avoid inconsistencies across parallel or batched reviews.
• No Header Level 1 Usage:
  All documentation and output should start with level 2 headers or lower for consistency and integration with Happycapy documentation standards.
• Refer to Upstream Docs:
  For detailed check patterns and integration with Director Gates, see .claude/docs/director-gates.md in the skill repository.

By ensuring robust, predictable argument handling, Phase 0: Parse Arguments lays a solid foundation for all subsequent analysis and reporting performed by the milestone-review skill.