Phase 1: Parse Arguments

Phase 1:

Parse Arguments

What Is This?

"Phase 1: Parse Arguments" is the initial processing step for the playtest-report skill on the Happycapy Skills platform. This phase is responsible for interpreting the command-line arguments supplied by the user when invoking this skill. The arguments determine the mode of operation-either generating a blank playtest report template or analyzing existing playtest notes-and establish the review mode, which configures the level of detail and focus for the report.

Why Use It?

Accurately parsing arguments is essential for interactive and automated tools, especially those that support multiple workflows or modes. For the playtest-report skill, parsing arguments ensures that the tool behaves predictably and that users can flexibly request different types of output (such as a new template or an analysis of notes) with the desired review granularity. This phase prevents ambiguity, reduces user error, and supports repeatable, standardized playtest reporting.

How to Use It

Argument Syntax

The skill expects arguments in the following form, as described by the argument-hint:

[new|analyze path-to-notes] [--review full|lean|solo]

• new: Generate a blank playtest report template.
• analyze path-to-notes: Analyze the specified playtest notes file and produce structured findings.
• --review full|lean|solo: Set the review mode (level of detail).

Argument Resolution Logic

The skill resolves the review mode using this priority order:

1. Explicit argument: If --review [full|lean|solo] is passed, use this value.
2. Persisted setting: Otherwise, check if production/review-mode.txt exists and read its value.
3. Default: If neither is provided, default to lean.

This logic is performed once and the result is stored for all subsequent invocations (gate spawns) during the current run, ensuring consistency.

Code Example

import sys
from pathlib import Path

def resolve_review_mode(args):
    # 1. Check for explicit --review argument
    if '--review' in args:
        idx = args.index('--review')
        if idx + 1 < len(args):
            return args[idx + 1]
    # 2. Check persisted setting
    review_file = Path('production/review-mode.txt')
    if review_file.exists():
        return review_file.read_text().strip()
    # 3. Default to 'lean'
    return 'lean'

def parse_arguments(args):
    if not args:
        raise ValueError("No arguments provided")
    mode = None
    notes_path = None
    if args[0] == 'new':
        mode = 'new'
    elif args[0] == 'analyze' and len(args) > 1:
        mode = 'analyze'
        notes_path = args[1]
    else:
        raise ValueError("Invalid arguments")
    review_mode = resolve_review_mode(args)
    return mode, notes_path, review_mode

## Example usage:
## args = sys.argv[1:]
## mode, notes_path, review_mode = parse_arguments(args)

When to Use It

Use this phase whenever you invoke the playtest-report skill, either interactively or via automation, to ensure that:

• The correct report generation mode is selected (new or analyze).
• The desired review mode is consistently applied, whether explicitly specified, previously set, or defaulted.
• The rest of the skill logic (template generation or note analysis) can proceed with the right context.

This phase is especially important in collaborative or CI/CD environments, where reproducibility and clarity are necessary.

Important Notes

• Single Responsibility: This phase is solely concerned with interpreting user input and establishing configuration state. It does not perform report generation or analysis.
• Persistence: The resolved review mode is applied for the duration of the current run to avoid inconsistency across multiple invocations.
• Validation: The arguments must be validated for correctness-incorrect formats or missing parameters should raise clear errors.
• Extensibility: As argument patterns evolve, this phase can be extended to support additional options or modes.

For more detailed parsing logic and integration patterns, refer to .claude/docs/director-gates.md in the source repository.

By following these conventions, the playtest-report skill ensures reliable, predictable, and user-friendly operation for structured playtest feedback workflows.