Phase 1: Determine Scope

Phase 1:

Determine Scope (perf-profile)

What Is This?

"Phase 1: Determine Scope" is the foundational step in the structured performance profiling workflow provided by the perf-profile skill on the Happycapy Skills platform. This skill is designed to help technical teams and individual developers systematically identify and prioritize performance bottlenecks within their codebase, using well-defined performance budgets and optimization recommendations. The first phase-Determine Scope-focuses on specifying exactly which part of your system will be analyzed and profiled, setting the direction for all subsequent profiling and optimization activities.

The perf-profile skill operates as an agent-driven, user-invocable tool, supporting various code analysis tasks through commands such as Read, Glob, Grep, and Bash. The determination of scope is the initial, critical step that defines whether profiling should cover the entire codebase or focus on a single, specified subsystem.

Why Use It?

Determining the scope before beginning any performance profiling session is essential for several reasons:

1. Efficiency: Profiling an entire codebase can be resource-intensive and time-consuming. By defining a clear scope, you ensure that profiling efforts are targeted and efficient, avoiding wasted effort on unrelated systems or modules.
2. Relevance: Many performance issues are localized to specific systems (e.g., rendering, physics, networking). Scoping allows you to focus only on the relevant code paths, data structures, or subsystems where problems are most likely or most impactful.
3. Clarity: A well-defined scope provides clarity for stakeholders, making it easy to communicate what is being analyzed and why. This is especially vital in collaborative environments, or when multiple teams are responsible for different systems.
4. Actionability: By scoping your profiling session, the findings and recommendations are more actionable and directly applicable to the chosen target area.

How to Use It

The "Determine Scope" phase of the perf-profile skill is straightforward but must be conducted with attention to project goals and system architecture. The skill uses a single argument to establish the scope:

• If you specify a system name (e.g., "physics", "render", "audio"), the profiling process will focus on that particular subsystem.
• If you specify "full", the profiling tool will run a comprehensive analysis across the entire codebase.

Example Usage:

Suppose you want to profile only the rendering system:

perf-profile "render"

Or, to profile everything:

perf-profile "full"

The skill will read the provided argument and adjust its profiling target accordingly. This argument should be chosen based on where you suspect performance issues to exist, or according to your team's current optimization priorities.

Integration with CI/CD:

The perf-profile skill can be integrated into automated build or test pipelines. For instance, you may configure your CI system to periodically run:

perf-profile "full"

on nightly builds, or restrict it to:

perf-profile "network"

when working on multiplayer features.

When to Use It

Use the "Determine Scope" phase whenever you are about to begin a structured performance profiling session, especially in the following scenarios:

• Before Major Releases: Ensuring performance budgets are met before shipping.
• After Feature Integration: When integrating new features into a subsystem (e.g., adding a new rendering effect).
• In Response to Reports: When profiling is triggered by user reports, QA findings, or automated monitoring that indicates performance regressions in a specific area.
• During Refactoring: When refactoring major systems and you want to ensure no new bottlenecks are introduced.

Choosing the correct scope ensures that your profiling efforts are directed and that your optimization work is both efficient and impactful.

Important Notes

• Check for Existing Budgets: After determining the scope, the next phase involves checking for existing performance budgets in design documentation or files like CLAUDE.md. These may define frame budgets (e.g., 16.67ms for 60fps), memory limits, and other targets that inform your profiling focus.
• Granularity Matters: Scoping too broadly (e.g., always using "full") may lead to an overwhelming amount of profiling data, making it difficult to prioritize issues. Conversely, scoping too narrowly may miss cross-system bottlenecks.
• Documentation: Clearly document the chosen scope for each profiling session. This practice aids reproducibility and helps other team members understand the context of your findings.
• Skill Limitations: The perf-profile skill relies on the argument you provide. If you are unsure of subsystem names or structure, consult your project’s documentation or codebase organization before invoking the skill.
• Iterative Profiling: It is common to begin with a broad scope, identify problematic systems, and then re-run the skill with a narrower focus for deeper analysis.

By starting with a well-defined scope, you lay the groundwork for efficient, targeted, and effective performance profiling and optimization using the Happycapy Skills platform.