Skip to content
Thåst Docs

Process

Standardised development methodology for UI improvements and feature implementation.

Version: 1.0 Last Updated: 2025-12-31

Process Overview

All significant changes follow this structured process:

┌─────────┐   ┌──────────────┐   ┌────────────┐   ┌──────────┐   ┌────────┐
│ Analyse │──►│ Plan (MD)    │──►│ Implement  │──►│  Test    │──►│ Deploy │
│         │   │              │   │            │   │          │   │        │
└─────────┘   └──────────────┘   └────────────┘   └──────────┘   └────────┘
     │              │                  │               │              │
     ▼              ▼                  ▼               ▼              ▼
  Research     Project MD         Code + Docs     Autonomous      Commit
  Industry     Success criteria   Inline docs     verification    Push
  Empirical    Rollback plan                      152+ tests

Phase 1: Analysis

Requirements

  • Empirical research with cited sources
  • Industry precedent review
  • Architecture impact assessment
  • Alternative approaches evaluated
  • Decision matrix with clear recommendation

Deliverable

docs/UI-ANALYSIS.md or similar analysis document

Quality Criteria

CriterionRequirement
Research depthMinimum 5 industry sources
AlternativesAt least 3 approaches compared
MetricsQuantified effort estimates
Decision clarityExplicit recommendation with rationale

Phase 2: Planning

Requirements

  • Detailed project markdown (PROJECT-X-NAME.md)
  • File-level change specification
  • Phase breakdown with time estimates
  • Verification checklist
  • Rollback plan
  • Success criteria

Project MD Structure

# PROJECT X: Title


**Status:** Planned | In Progress | Complete
**Priority:** High | Medium | Low
**Estimated Effort:** Xh
**Risk Level:** Low | Medium | High


## Objective
Clear statement of what and why


## Scope
### Files to Modify
| File | Action | Lines |
### Components Affected
List with descriptions


## Development Process
### Phase 1: Name (Xh)
- [ ] Task 1
- [ ] Task 2


## Verification Checklist
### Functional Tests
### Regression Tests
### Performance Tests


## Rollback Plan
Step-by-step reversion


## Success Criteria
Measurable outcomes


## Post-Implementation Notes
Actual effort, issues, lessons

Quality Criteria

CriterionRequirement
GranularityTasks ≤ 2h each
TestabilityEvery change verifiable
ReversibilityComplete rollback possible
TraceabilityLinks to analysis document

Phase 3: Implementation

Requirements

  • No magic numbers (use named constants)
  • Pure functions where possible
  • No breaking changes to existing APIs
  • Inline documentation for non-obvious logic

Code Quality Standards

/**
 * Calculate true peak using polyphase FIR filter.
 *
 * Implements ITU-R BS.1770-4 Annex 2 compliant 4× oversampling
 * using 12-tap polyphase decomposition of 48-tap prototype filter.
 *
 * @param {Float32Array} samples - Input audio samples
 * @returns {number} Maximum intersample peak in linear scale
 */
function calculateTruePeakPolyphase(samples) {
  // Guard: insufficient samples for filter
  if (!samples || samples.length < POLYPHASE_TAPS_PER_PHASE) {
    return 0;
  }
  // ... implementation
}

Commit Standards

<type>: <description>


<body - what and why>

Types: feat, fix, refactor, docs, test, chore

Phase 4: Testing

Autonomous Test Requirements

  1. Unit Tests — Pure function verification
  2. Integration Tests — Component interaction
  3. Regression Tests — Existing functionality preserved
  4. Performance Tests — No degradation

Test Execution

Terminal window
# Run all tests
node tests/metering-verification.js
node tests/storage-migration-test.js
node tests/calibration-profiles-test.js
node tests/rest-api-test.js


# Expected: All tests pass

Manual Verification

Browser-based testing for:

  • Visual rendering
  • User interactions
  • Responsive layouts
  • Touch functionality

Phase 5: Documentation

Requirements

  • Update relevant docs/*.md files
  • Mark obsolete features clearly

Documentation Checklist

[ ] ARCHITECTURE.md updated if structure changed
[ ] IMPROVEMENTS.md updated with new features
[ ] README.md updated if user-facing
[ ] Inline code comments complete
[ ] Project MD post-implementation notes filled

Phase 6: Deployment

Pre-Push Checklist

[ ] All tests pass (152+)
[ ] No console errors in browser
[ ] Git status clean
[ ] Commit message follows standard
[ ] Documentation complete

Push Process

Terminal window
git add -A
git status  # Verify changes
git commit -m "..."
git push

Quality Assessment: Project MDs

PROJECT-A-DRAG-DROP-REMOVAL.md

CriterionScoreNotes
Objective clarity5/5Clear purpose with 5 benefits listed
Scope definition5/5File-level detail with line counts
Phase breakdown5/55 phases with time estimates
Verification5/5Functional, regression, performance checklists
Rollback plan5/5Single-command reversion
Code examples5/5Exact lines to remove provided
Overall30/30Senior-level documentation

PROJECT-B-REMOTE-CONTROL.md

CriterionScoreNotes
Architecture diagram5/5Clear before/after state
Protocol specification5/5TypeScript interfaces
Implementation phases5/55 phases with estimates
Security considerations5/5LAN-only + optional auth
Test scenarios5/5Unit, integration, E2E
Success criteria5/5Measurable metrics
Overall30/30Senior-level documentation

Industry Alignment

Both project MDs follow best practices from:

  • RFC 2119 — Requirement levels (MUST, SHOULD, MAY)
  • ADR (Architecture Decision Records) — Decision documentation
  • INVEST criteria — Independent, Negotiable, Valuable, Estimable, Small, Testable
  • Definition of Done — Clear completion criteria

Process Compliance Checklist

For each project, verify:

[ ] Analysis document exists with research
[ ] Project MD follows template
[ ] All phases have time estimates
[ ] Verification checklist complete
[ ] Rollback plan documented
[ ] Success criteria measurable
[ ] Post-implementation notes template ready
[ ] No breaking changes to existing code