StarPunk/docs/design/v1.5.0/2025-12-16-developer-questions.md

# Developer Review Questions - v1.5.0 Release Plan

**Date**: 2025-12-16
**Reviewer**: StarPunk Developer Agent
**Documents Reviewed**:
- `docs/decisions/ADR-062-timestamp-based-slug-format.md`
- `docs/projectplan/v1.5.0/RELEASE.md`
- `docs/projectplan/BACKLOG.md`

## Executive Summary

After thorough review of the v1.5.0 release plan and ADR-062, I have identified **8 questions** that need clarification from the architect before implementation can begin. These questions fall into three categories:

1. **Slug implementation details** (Questions 1-4)
2. **Test structure and expectations** (Questions 5-6)
3. **Phase dependencies and ordering** (Questions 7-8)

The majority of questions concern Phase 1 (Timestamp-Based Slugs), which has some ambiguities around collision handling and interaction with existing code paths.

---

## Questions

### Phase 1: Timestamp-Based Slugs

#### Q1: Collision handling function location and signature

**Issue**: ADR-062 specifies an `ensure_unique_slug(base_slug: str) -> str` function that checks `slug_exists(base_slug)`, but the implementation location and database interaction pattern are unclear.

**Current State**:
- `starpunk/slug_utils.py` has `make_slug_unique_with_suffix(base_slug, existing_slugs: Set[str])` that takes a pre-fetched set
- `starpunk/utils.py` has `make_slug_unique(base_slug, existing_slugs: set[str])` with random suffix logic
- `starpunk/notes.py` line 220 calls `_get_existing_slugs(db)` to fetch all slugs, then passes to uniqueness check

**Questions**:
1. Should `ensure_unique_slug()` perform its own database queries (violates current pattern)?
2. Or should it follow the existing pattern of accepting `existing_slugs: Set[str]` parameter?
3. Should this function live in `slug_utils.py` or `utils.py`?
4. The ADR shows `slug_exists()` as a separate function - should this be implemented, or is this pseudocode?

**Implementation Impact**: This affects the function signature and which module needs modification. The current codebase consistently passes pre-fetched slug sets to avoid N+1 queries.

**Suggested Clarification**: Confirm whether to:
- Keep existing pattern: `ensure_unique_slug(base_slug: str, existing_slugs: Set[str]) -> str`
- Or introduce database coupling: `ensure_unique_slug(base_slug: str, db: Connection) -> str`

---

#### Q2: Sequential suffix starting number

**Issue**: ADR-062 says "first collision: `20251216143052-1`" but the examples table shows the second note as `-1`, implying the first note has no suffix.

**Current State**:
- Existing `make_slug_unique_with_suffix()` starts at `-2` for first collision (base slug is attempt #1)
- This matches table in ADR-062 examples

**Questions**:
1. Does "first collision" mean the first duplicate attempt (which should get `-1`)?
2. Or does it mean the first note gets the base slug, and second note gets `-1`?

**Example Scenario**:
```python
# Two notes created at exactly 2025-12-16 14:30:52
Note A created first: slug = ?
Note B created second: slug = ?

# Is it:
Option 1: A = 20251216143052, B = 20251216143052-1  (matches table)
Option 2: A = 20251216143052-1, B = 20251216143052-2  (matches "first collision" text)
```

**Implementation Impact**: Determines whether sequential suffix loop starts at 1 or 2.

**Suggested Clarification**: Confirm that first note gets base slug (no suffix), first collision gets `-1`.

---

#### Q3: Two `generate_slug()` functions with different signatures

**Issue**: The codebase has two `generate_slug()` functions:

**Current State**:
- `starpunk/utils.py` line 173: `generate_slug(content: str, created_at: Optional[datetime]) -> str`
  - Content-based slug generation (extracts words)
  - Used by `notes.py` line 230
- ADR-062 specifies: `generate_slug(custom_slug: str = None, created_at: datetime = None) -> str`
  - Timestamp-based, no content parameter

**Questions**:
1. Should I replace the function in `utils.py`?
2. Should I create a new function in `slug_utils.py` and leave `utils.py` as deprecated?
3. Should both functions coexist with different names?
4. The removal of the `content` parameter is a breaking change for `notes.py` - should `notes.py` be updated to not pass content at all?

**Implementation Impact**:
- If replacing `utils.py` function: ~15 test files will need updates
- If creating new function: need to update all callers to use new function
- `notes.py` line 230 currently calls `generate_slug(content, created_at)` - this will break

**Suggested Clarification**: Specify exact function location and migration path for callers.

---

#### Q4: Reserved slug handling in timestamp context

**Issue**: ADR-062 doesn't address what happens if a timestamp-based slug conflicts with a reserved slug.

**Current State**:
- Reserved slugs: `['api', 'admin', 'auth', 'feed', ...]` (all alphabetic)
- Timestamp format: `20251216143052` (all numeric)
- **These can never collide**

**Questions**:
1. Should reserved slug validation be removed from the default slug path since timestamps can't conflict?
2. Should it remain for safety/future-proofing?
3. Custom slugs still need reserved validation - should this logic split?

**Implementation Impact**: May simplify code by removing unnecessary validation from timestamp path.

**Suggested Clarification**: Confirm whether reserved slug check is still needed for default slugs.

---

### Phase 0: Test Fixes

#### Q5: Test update strategy for slug format changes

**Issue**: Phase 1 will change default slug format from content-based to timestamp-based. Many tests currently assert content-based slugs.

**Current State**:
- `tests/test_utils.py` has 20+ tests asserting content-based slug behavior (e.g., `assert slug == "hello-world-this-is-my"`)
- Phase 1 acceptance criteria: "Update expected slug formats in test assertions"

**Questions**:
1. Should these tests be updated to assert timestamp format (e.g., `assert slug.startswith("2025")`)?
2. Should the old content-based tests be preserved but marked as testing legacy behavior?
3. Should tests be split: "default slug generation" vs "content-based slug generation" (if we keep the old function)?
4. Do you want all slug assertions to use pattern matching (timestamp format) or fixed timestamps in tests?

**Implementation Impact**:
- Affects ~30 test assertions in `test_utils.py`
- Affects ~10 integration tests in `test_notes.py`, `test_micropub.py`
- May require test helper functions for deterministic timestamps

**Suggested Clarification**: Provide guidance on test update strategy.

---

#### Q6: Phase 0 priority - are tests blocking?

**Issue**: Phase 0 is marked "Must complete first - unblocks all other phases" but the 19 failing tests appear unrelated to slug changes.

**Current State**:
- Failing tests: Migration performance, feed streaming, content negotiation, search security
- None directly related to slug generation
- Phase 1 (slugs) could theoretically proceed with these tests failing

**Questions**:
1. Is Phase 0 truly blocking for Phase 1, or can Phase 1 proceed if slug-related tests pass?
2. Should Phase 0 be completed before ANY other phase, or just before phases that depend on those specific test areas?
3. If I discover that fixing some Phase 0 tests requires changes that conflict with Phase 1 work, what's the priority?

**Implementation Impact**: Affects work sequencing and potential merge conflicts.

**Suggested Clarification**: Confirm hard dependency of Phase 0 on all other phases, or allow parallel work.

---

### General Implementation Questions

#### Q7: Backwards compatibility for existing notes

**Issue**: ADR-062 states "Existing notes retain their slugs (no data migration)" but doesn't specify how the dual slug formats coexist.

**Current State**:
- Database has notes with content-based slugs (e.g., `my-first-post`)
- New notes will have timestamp slugs (e.g., `20251216143052`)
- Both slug formats will exist simultaneously

**Questions**:
1. Do any code paths need to detect/handle the two formats differently?
2. Should there be a helper function `is_timestamp_slug(slug: str) -> bool` for future use?
3. Are there any edge cases where code assumes slug format (e.g., sorting, display, URLs)?
4. Does feed generation or UI need updates to handle mixed slug formats?

**Implementation Impact**: May require audit of all slug usages to ensure format-agnostic handling.

**Suggested Clarification**: Confirm if any code needs to be format-aware, or if slug format is truly opaque.

---

#### Q8: Phase ordering rationale

**Issue**: Phases 2-4 are all marked "Phase 0 complete" as dependency, but no interdependencies are noted between them.

**Current State**:
- Phase 2: Debug file management
- Phase 3: N+1 query fix (feed generation)
- Phase 4: Atomic variant generation
- All independent of each other

**Questions**:
1. Can Phases 2-4 be implemented in parallel after Phase 0?
2. Is there a preferred order (2→3→4) for any reason?
3. Should each phase be committed separately or can they be batched?

**Implementation Impact**: Affects work planning and commit structure.

**Suggested Clarification**: Confirm whether Phases 2-4 can be parallelized or should be sequential.

---

## Additional Observations (Not Blocking)

These observations don't block implementation but may inform architectural decisions:

### O1: Code duplication between `utils.py` and `slug_utils.py`

**Observation**: Reserved slugs are defined in both:
- `utils.py` line 24: `RESERVED_SLUGS = {"admin", "api", ...}` (5 items)
- `slug_utils.py` line 24: `RESERVED_SLUGS = frozenset([...])` (12 items, more comprehensive)

**Impact**: Low - but may cause confusion. Consider consolidating in v1.5.1.

---

### O2: Timestamp format consistency

**Observation**: ADR-062 uses `YYYYMMDDHHMMSS` (no separator) but existing fallback in `utils.py` line 220 uses `YYYYMMDD-HHMMSS` (with hyphen).

**Questions**:
- Is the hyphen removal intentional (shorter, more compact)?
- Current: `20241118-143045` (15 chars)
- ADR-062: `20241118143045` (14 chars)

**Impact**: Minor - affects slug length by 1 character.

---

### O3: Test coverage gap mentioned in Phase 5

**Observation**: Phase 5 mentions "MPO format handling (untested)" but this is already in BACKLOG as "High priority - Scheduled for v1.5.0".

**Question**: Is this intentionally listed in both BACKLOG and Phase 5, or is there duplication?

**Impact**: None - just a clarity question.

---

## Summary

**Implementation Readiness**: 6/10

The release plan is well-structured with clear phases and acceptance criteria. However, **Phase 1 (Timestamp-Based Slugs)** has enough ambiguity in implementation details (Questions 1-4) that I cannot confidently proceed without architect clarification.

**Recommended Next Steps**:
1. Architect addresses Questions 1-4 (Phase 1 blocking issues)
2. Architect clarifies Questions 5-8 (helps inform implementation approach)
3. Developer proceeds with Phase 0 (test fixes) while awaiting Q1-Q4 answers
4. Developer implements Phases 1-4 after clarifications received

**Estimated Time to Implementation-Ready**: 1-2 hours for architect to address questions.

---

## Approval

Once these questions are addressed, I am confident the implementation can proceed smoothly with the 18-29 hour estimate provided in the release plan.

**Developer**: StarPunk Developer Agent
**Status**: Awaiting Architect Response
**Next Action**: Architect to review and answer questions 1-8