Duplicate Pokemon catches allowed - unclear if intentional or missing validation

[tomblancdev]

Description

The `submitQuizResult` handler adds Pokemon to the pokedex without checking if the same Pokemon was already caught in the same topic/course. While this may be intentional (catch duplicates), there's no clear documentation of this behavior.

Location

`src/mcp-server/src/tools/quiz.ts` - `submitQuizResultHandler` (lines 278-312)

Current Behavior

```typescript
// Add Pokemon to pokedex if caught
if (passed) {
const pokedexResult = await readYaml("pokedex.yaml");
if (pokedexResult.success && pokedexResult.data) {
const pokedex = pokedexResult.data;

const newPokemon: PokemonEntry = {
  id: \`\${session.pokemon.name.toLowerCase()}-\${Date.now()}\`,  // Unique ID by timestamp
  // ...
};

pokedex.pokemon.push(newPokemon);  // Always adds, no duplicate check
// ...

}
}
```

Design Questions

1. Should users be able to catch multiple of the same Pokemon species?
2. If yes, is this intentional or a missing feature?
3. Should there be a "shiny" variant for repeat catches?

Potential UX Issues

• User catches Pikachu for docker/basics
• User catches another Pikachu for docker/basics (same quiz retaken)
• Pokedex now shows two identical Pikachus

Expected Behavior Options

Option A: Allow duplicates (current, but document it)

Document that retaking quizzes gives new Pokemon, like Pokemon GO.

Option B: Prevent duplicates per topic/course

```typescript
const existingPokemon = pokedex.pokemon.find(
p => p.pokedex_number === session.pokemon.pokedexNumber
&& p.topic === session.topic
&& p.course === session.course
);
if (existingPokemon) {
// Award points but no duplicate Pokemon
}
```

Option C: "Candy" system like Pokemon GO

Duplicate catches give "evolution candy" instead.

Suggested Action

Document the intended duplicate behavior in user-guide.md and CLAUDE.md.

[tomblancdev]

Technical Analysis

Root Cause

The submitQuizResultHandler adds Pokemon to the pokedex without checking for duplicates:

// src/mcp-server/src/tools/quiz.ts:278-311
if (passed) {
  const pokedexResult = await readYaml<PokedexData>("pokedex.yaml");
  if (pokedexResult.success && pokedexResult.data) {
    const pokedex = pokedexResult.data;

    const newPokemon: PokemonEntry = {
      id: \`\${session.pokemon.name.toLowerCase()}-\${Date.now()}\`,  // Unique by timestamp
      pokedex_number: session.pokemon.pokedexNumber,
      name: session.pokemon.name,
      // ...
    };

    pokedex.pokemon.push(newPokemon);  // Always adds
    pokedex.stats.total_caught += 1;   // Always increments

Current Behavior

Session 1:

• User takes docker/basics quiz
• Catches Pikachu (id: pikachu-1704000000000)
• Pokedex: 1 Pokemon

Session 2 (same quiz retaken):

• User retakes docker/basics quiz
• Catches another Pikachu (id: pikachu-1704000001000)
• Pokedex: 2 Pokemon (both Pikachu)

Design Considerations

Arguments FOR allowing duplicates:

1. Pokemon GO model - catching same species is normal
2. Quiz retakes should still reward effort
3. "Candy" for evolution could be implemented later
4. Collection completeness vs unique completeness

Arguments AGAINST duplicates:

1. Feels like cheating/grinding
2. "Pokedex" traditionally tracks unique species
3. Inflates total_caught stat
4. Storage growth (point_history array grows unbounded - implement pruning or archival #61 point_history unbounded)

Implementation Options

Option A: Document Current Behavior (Recommended Short-term)
Add to user-guide.md and CLAUDE.md:

## Pokemon Catching
- Retaking quizzes can catch the same Pokemon species multiple times
- Each catch is unique (like Pokemon GO)
- Use evolution to upgrade your collection

Option B: Prevent Same-Session Duplicates

// Check if this exact Pokemon/topic/course combo exists
const existingCatch = pokedex.pokemon.find(
  p => p.pokedex_number === session.pokemon.pokedexNumber
    && p.topic === session.topic
    && p.course === session.course
);

if (existingCatch) {
  return {
    success: true,
    passed: true,
    pokemon: {
      caught: false,
      name: session.pokemon.name,
      message: \`\${session.pokemon.name} was already caught for this course! Points still awarded.\`,
    },
    points: { earned: pointsResult.total },
  };
}

Option C: "Candy" System

const existingCatch = pokedex.pokemon.find(
  p => p.pokedex_number === session.pokemon.pokedexNumber
);

if (existingCatch) {
  // Award "candy" instead of duplicate
  existingCatch.candy = (existingCatch.candy || 0) + 1;
  
  return {
    success: true,
    passed: true,
    pokemon: {
      caught: false,
      name: session.pokemon.name,
      message: \`You got a \${session.pokemon.name} candy! (Total: \${existingCatch.candy})\`,
    },
    // ...
  };
}

Option D: Shiny Variant for Duplicates

const existingCatch = pokedex.pokemon.find(
  p => p.pokedex_number === session.pokemon.pokedexNumber && !p.shiny
);

if (existingCatch) {
  // Small chance for shiny
  const isShiny = Math.random() < 0.1;  // 10% chance
  if (isShiny) {
    // Add shiny variant
    newPokemon.shiny = true;
    newPokemon.sprites.front = \`shiny-\${newPokemon.sprites.front}\`;
  } else {
    // Skip duplicate
    return {...};
  }
}

Recommended Approach

1. Short-term: Document current behavior (it's a valid game design)
2. Medium-term: Implement duplicate detection per topic/course
3. Long-term: Consider candy/evolution system

Estimated Complexity

Option	Complexity	Time
A (Documentation)	Trivial	15 min
B (Block duplicates)	Simple	30 min
C (Candy system)	Moderate	2-3 hours
D (Shiny system)	Moderate	2-3 hours

Dependencies

• Consider with point_history array grows unbounded - implement pruning or archival #61 (unbounded growth)
• May need pokedex type update for candy/shiny fields

Testing Checklist

• First catch of species works
• Duplicate catch behavior documented/handled
• Stats accurately reflect catches
• Points still awarded for duplicates (if allowed)