# Learn to Gadget: High Scores Feature Example

## Introduction

This project is provided as a **starter kit for learning to use Gadget**, not as a game to play or a template for game design. It demonstrates how to use the Gadget Code system to add features to a project through the **Plan, Build, Test, and Ship** workflow.

The example feature we'll walk through is adding a **High Scores** system to the Gab Invaders game. This feature will:
- Store high scores in `localStorage`
- Allow players to enter their initials (3 alphanumeric characters)
- Display the top scores on a leaderboard

**Important:** We are **not actually implementing** this feature in this documentation. Instead, we present an example of the **process** you would follow when using Gadget to add a feature. This document shows you how to structure your prompts and what to expect at each stage.

---

## Why Define Features Well?

Before diving into the workflow, it's crucial to understand that **how you define a feature directly impacts the quality of the result**. Gadget is an AI agent that needs clear, specific instructions to produce the right output.

### Key Principles for Feature Definition:

1. **Be Specific About Requirements**: Don't just say "add high scores." Specify storage mechanism, input format, display location, etc.

2. **Define Acceptance Criteria**: What does "done" look like? What edge cases need handling?

3. **Consider the User Experience**: How will players interact with this feature? What's the flow?

4. **Think About Data Structure**: How will the data be stored and retrieved?

5. **Plan for Edge Cases**: What happens when localStorage is full? What if a player enters invalid characters?

---

## The Workflow: Plan, Build, Test, Ship

### Step 1: PLAN

**Goal:** Define the feature requirements and create a plan for implementation.

**Example Prompt:**

```
I want to add a High Scores feature to the Gab Invaders game. Here are the requirements:

1. Store high scores in localStorage
2. Allow players to enter their initials (exactly 3 alphanumeric characters)
3. Display a leaderboard showing the top 5 scores
4. Each score entry should include: initials, score, and date
5. Handle edge cases: invalid input, localStorage full, etc.

Please create a plan for implementing this feature. Include:
- Data structure for storing scores
- Validation logic for initials
- Display component for the leaderboard
- Any necessary state management

Define what "done" looks like for this feature.
```

**Expected Output from Gadget:**

Gadget should respond with a detailed plan including:
- File structure changes needed
- Data model for scores
- Component architecture
- Test cases to write
- Acceptance criteria

**Your Action:** Review the plan. If it doesn't match your vision, refine your prompt and try again. This is where you learn to communicate effectively with Gadget.

---

### Step 2: BUILD

**Goal:** Implement the feature according to the plan.

**Example Prompt:**

```
Based on the plan we created, please implement the High Scores feature:

1. Create the score data structure and storage logic
2. Add the initials input component
3. Implement validation for 3 alphanumeric characters
4. Create the leaderboard display component
5. Wire everything together

Make sure to:
- Follow the existing code style
- Add appropriate error handling
- Include comments explaining the code
- Not break existing functionality
```

**Expected Output from Gadget:**

Gadget should:
- Create new files or modify existing ones
- Implement the score storage and retrieval
- Add the UI components
- Ensure the game still works correctly

**Your Action:** Review the code changes. Check that:
- The code follows best practices
- The implementation matches the plan
- No existing functionality was broken
- The code is clean and well-documented

If something is wrong, use `file_edit` or provide feedback to Gadget to fix it.

---

### Step 3: TEST

**Goal:** Verify the feature works correctly and doesn't break existing functionality.

**Example Prompt:**

```
Please write and run tests for the High Scores feature:

1. Test score storage and retrieval
2. Test initials validation (accept valid, reject invalid)
3. Test leaderboard display
4. Test edge cases (empty storage, localStorage full, etc.)
5. Ensure existing game functionality still works

Run the test suite and report results. If any tests fail, fix the issues.
```

**Expected Output from Gadget:**

Gadget should:
- Create test files for the new feature
- Run the existing test suite
- Report pass/fail status
- Fix any issues found

**Your Action:** Review the test results. Ensure:
- All tests pass
- Edge cases are covered
- The feature works as expected
- No regressions in existing functionality

---

### Step 4: SHIP

**Goal:** Prepare and deploy the feature for production.

**Example Prompt:**

```
The High Scores feature is complete and tested. Please:

1. Create a git tag for this release
2. Update any necessary documentation
3. Prepare the release notes
4. Deploy to production (or staging if appropriate)
5. Verify the deployment was successful

Provide a summary of what was shipped and any deployment notes.
```

**Expected Output from Gadget:**

Gadget should:
- Create a git tag (e.g., `v1.1.0-high-scores`)
- Update CHANGELOG or release notes
- Deploy to the target environment
- Verify the deployment
- Provide a deployment summary

**Your Action:** Review the deployment:
- Check that the release was created correctly
- Verify the deployment succeeded
- Confirm the feature is live and working
- Monitor for any issues

---

## Learning Outcomes

By working through this example, you should learn:

1. **How to structure feature requests** for Gadget
2. **How to review and validate** Gadget's work at each stage
3. **How to iterate** when the first attempt isn't perfect
4. **How to communicate** your requirements clearly
5. **How to use the Plan, Build, Test, Ship workflow** effectively

## Next Steps

Now that you understand the workflow:

1. Try adding a different feature to the project
2. Experiment with different prompt styles
3. Learn to recognize when Gadget needs clarification
4. Build your own mental model of how Gadget works

Remember: **Gadget is a tool, not an oracle.** The quality of the output depends on the quality of your input. Learn to define features well, and you'll get great results.

---

## Tips for Better Results

- **Be specific**: Vague prompts lead to vague results
- **Provide context**: Help Gadget understand the project structure
- **Review everything**: Don't assume Gadget got it right the first time
- **Iterate**: It's okay to refine your prompts
- **Learn from failures**: When things go wrong, understand why and adjust

## Conclusion

This project is your playground for learning Gadget. Use it to experiment, make mistakes, and learn. The High Scores example shows you the process—now it's your turn to apply it to real features.

Happy coding!