Full sync - all projects, memory, configs
This commit is contained in:
242
data/tasks/learning-feed-spec.md
Normal file
242
data/tasks/learning-feed-spec.md
Normal file
@ -0,0 +1,242 @@
|
||||
# Learning Feed — Personal Knowledge Feed App
|
||||
|
||||
**Priority:** HIGH
|
||||
**Assigned:** Glitch
|
||||
**Date:** 2026-03-13
|
||||
**Requested by:** D J
|
||||
|
||||
---
|
||||
|
||||
## Concept
|
||||
|
||||
A social media-style infinite scroll feed where every "post" is an AI-generated learning nugget. Hijacks the dopamine loop of social media scrolling but replaces the content with real knowledge. Designed for people who don't "sit down to study" but check their phone 50+ times a day.
|
||||
|
||||
**This is a personal tool, not a product. No monetization, no auth, no multi-user.**
|
||||
|
||||
---
|
||||
|
||||
## Core Experience
|
||||
|
||||
The app should feel like opening Instagram or Twitter — not like opening a textbook.
|
||||
|
||||
### The Feed
|
||||
- Infinite scroll of "posts" that look like social media content
|
||||
- Each post is a bite-sized learning nugget (1-3 paragraphs max)
|
||||
- Mixed post formats to keep it interesting (see Post Types below)
|
||||
- Fake "authors" with avatars and names to make it feel like a real feed (e.g. "Dr. Sarah Chen · Tax Strategy" or "Marcus Webb · Real Estate")
|
||||
- Timestamps ("2h ago", "Yesterday") — cosmetic, makes it feel alive
|
||||
- Clean, mobile-first design — this lives on D J's iPhone
|
||||
|
||||
### Post Types (variety prevents fatigue)
|
||||
1. **Quick Fact** — "Did you know: A 1031 exchange lets you defer capital gains tax by reinvesting sale proceeds into a like-kind property within 180 days."
|
||||
2. **Deep Dive** — Longer post (expandable) explaining a concept in detail with examples
|
||||
3. **Quiz/Challenge** — "What's the monthly payment on a $276K loan at 6.25% over 30 years?" with reveal on tap
|
||||
4. **Myth Buster** — "MYTH: You need 20% down to buy a house. REALITY: FHA loans require as little as 3.5%."
|
||||
5. **Comparison** — Side-by-side: "S&P 500 vs Real Estate: 20-year returns comparison"
|
||||
6. **Story/Case Study** — "How Warren Buffett made $2.6B from a single Coca-Cola investment in 1988"
|
||||
7. **Number of the Day** — "$337,877 — The amount of passive losses that accumulate over 5 years on a $345K rental property at >$150K AGI"
|
||||
8. **Chain/Thread** — Multi-part posts that build on each other (Part 1 of 3)
|
||||
|
||||
### Interaction
|
||||
- **Tap to expand** — Deep dives and quiz answers expand inline
|
||||
- **Save/Bookmark** — Star posts to review later
|
||||
- **Got It / Already Knew This** — Light feedback so the AI knows your level
|
||||
- **More Like This** — Tells the system to generate more on this topic
|
||||
- **Surprise Me** — Shuffle in random topics
|
||||
|
||||
---
|
||||
|
||||
## Topic System
|
||||
|
||||
### Seeded Topics
|
||||
- User picks initial interests from a list or types custom topics
|
||||
- These seed the initial feed generation
|
||||
- Stored in a simple JSON config
|
||||
|
||||
### Dynamic Expansion
|
||||
- Track which posts the user engages with (expands, saves, "more like this")
|
||||
- AI uses engagement patterns to introduce adjacent/related topics
|
||||
- Example: User reads about cap rates → system introduces DSCR, NOI, 1031 exchanges
|
||||
- Gradual difficulty progression — start with basics, introduce advanced concepts as engagement shows comprehension
|
||||
|
||||
### Surprise Layer
|
||||
- 10-20% of feed is random interesting content outside the user's topic bubbles
|
||||
- History, science, psychology, economics, technology
|
||||
- Mimics serendipity of a real social feed
|
||||
- If user engages with a surprise topic, it can become a seeded topic
|
||||
|
||||
### On-Demand Topics
|
||||
- Text input: "teach me about options trading"
|
||||
- Floods the feed with that topic for the next ~20 posts, then blends back to normal mix
|
||||
|
||||
---
|
||||
|
||||
## Spaced Repetition (Hidden)
|
||||
|
||||
This is the secret sauce. The feed naturally resurfaces content for retention:
|
||||
|
||||
- **Day 1:** New fact appears
|
||||
- **Day 3:** Same fact reappears as a quiz ("Do you remember...?")
|
||||
- **Day 7:** Fact appears in a different format (comparison, myth buster, deeper context)
|
||||
- **Day 14:** Quick recall quiz
|
||||
- **Day 30:** Final reinforcement
|
||||
|
||||
The user never sees "spaced repetition" — it just feels like the feed naturally revisits things. Like how Twitter shows you things you liked from last week.
|
||||
|
||||
Track each post's retention schedule in the database.
|
||||
|
||||
---
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### Stack
|
||||
- **Next.js 16** (App Router) — standard stack
|
||||
- **Tailwind CSS v4**
|
||||
- **Framer Motion** — smooth animations, card transitions, expand/collapse
|
||||
- **ShadCN UI** — component library
|
||||
- **Lucide Icons**
|
||||
- **TypeScript**
|
||||
- **SQLite** (via better-sqlite3) — local database, no external dependencies
|
||||
- **AI Generation** — Claude API via Anthropic SDK (use D J's existing API key)
|
||||
|
||||
### Data Model
|
||||
|
||||
```
|
||||
topics (id, name, category, seed_or_discovered, engagement_score, created_at)
|
||||
posts (id, topic_id, post_type, title, content, expanded_content, author_name, author_avatar, author_specialty, difficulty, created_at, generated_at)
|
||||
interactions (id, post_id, type [view/expand/save/got_it/more_like_this], created_at)
|
||||
retention_schedule (id, post_id, stage [new/day3/day7/day14/day30], scheduled_at, shown_at, recalled)
|
||||
feed_requests (id, topic_override, created_at) -- for on-demand topic floods
|
||||
```
|
||||
|
||||
### API Routes
|
||||
- `GET /api/feed` — returns next batch of posts (mix of new + retention + surprise)
|
||||
- `POST /api/feed/generate` — triggers AI generation of new posts for topics
|
||||
- `POST /api/interact` — log interaction (view, expand, save, got_it, more_like_this)
|
||||
- `GET /api/topics` — list current topics with engagement scores
|
||||
- `POST /api/topics` — add/remove seeded topics
|
||||
- `POST /api/topics/request` — on-demand topic flood
|
||||
- `GET /api/saved` — bookmarked posts
|
||||
- `GET /api/stats` — learning stats (posts read, topics explored, retention rate)
|
||||
|
||||
### Feed Algorithm
|
||||
1. Pull retention-scheduled posts due today (highest priority — these are reinforcement)
|
||||
2. Pull new posts from seeded topics (weighted by engagement score)
|
||||
3. Pull 10-20% surprise posts
|
||||
4. If topic override active, weight heavily toward that topic
|
||||
5. Mix and shuffle for natural feel
|
||||
6. Never show the same post twice in one session (except retention)
|
||||
|
||||
### AI Generation
|
||||
- Use Claude Sonnet (cost-effective for content generation)
|
||||
- Batch generate: create 20-50 posts per topic in advance, store in DB
|
||||
- Background generation: when post inventory for a topic drops below threshold, auto-generate more
|
||||
- System prompt should specify: post type, topic, difficulty level, target length
|
||||
- Generate fake author profiles per topic area (reuse for consistency)
|
||||
|
||||
### Pre-seeded Authors (examples)
|
||||
- "Dr. Sarah Chen" — Tax & Financial Strategy
|
||||
- "Marcus Webb" — Real Estate Investing
|
||||
- "Alex Rivera" — Crypto & Blockchain
|
||||
- "Prof. James Okafor" — Economics & Markets
|
||||
- "Nina Patel" — Technology & Engineering
|
||||
- "Ray Tanaka" — History & Culture
|
||||
- Generate more as topics expand
|
||||
|
||||
---
|
||||
|
||||
## UI Design
|
||||
|
||||
### Mobile-First Layout
|
||||
- Single column feed (like Instagram/Twitter)
|
||||
- Pull to refresh
|
||||
- Smooth scroll with card-based posts
|
||||
- Bottom nav: Feed | Saved | Topics | Stats
|
||||
|
||||
### Post Card Design
|
||||
- Author avatar (small circle) + name + specialty + timestamp
|
||||
- Post type badge (small pill: "Quick Fact", "Quiz", "Deep Dive", etc.)
|
||||
- Content area
|
||||
- Expandable section (tap to reveal for quizzes/deep dives)
|
||||
- Action bar: Save ⭐ | Got It ✓ | More Like This 🔄
|
||||
- Clean, readable typography — no clutter
|
||||
|
||||
### Topics Page
|
||||
- Grid/list of active topics with engagement indicators
|
||||
- Add topic button (text input)
|
||||
- Toggle topics on/off
|
||||
- "Discover" section showing topics the AI is introducing based on your engagement
|
||||
|
||||
### Saved Page
|
||||
- Bookmarked posts in reverse chronological order
|
||||
- Search/filter by topic
|
||||
|
||||
### Stats Page
|
||||
- Posts read today / this week / all time
|
||||
- Topics explored
|
||||
- Retention rate (% of spaced repetition quizzes answered correctly)
|
||||
- Streak (days in a row you opened the app)
|
||||
- Simple, motivating — not gamified to the point of being annoying
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
- Run as systemd service on D J's VM (192.168.86.45)
|
||||
- Port: 3001 (knowledge-builder is archived, port is free)
|
||||
- Mobile access via local network or Cloudflare tunnel for remote access
|
||||
- PWA manifest so it can be added to iPhone home screen (feels like a native app)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 (MVP)
|
||||
|
||||
1. Feed page with infinite scroll
|
||||
2. 3 post types: Quick Fact, Quiz, Deep Dive
|
||||
3. Seeded topics (manual config)
|
||||
4. AI post generation (Claude Sonnet)
|
||||
5. Basic interactions (expand, save)
|
||||
6. SQLite storage
|
||||
7. Mobile-responsive
|
||||
8. PWA manifest (add to home screen)
|
||||
|
||||
## Phase 2
|
||||
|
||||
1. All 8 post types
|
||||
2. Dynamic topic expansion based on engagement
|
||||
3. Spaced repetition engine
|
||||
4. On-demand topic floods
|
||||
5. Stats page
|
||||
6. Fake author system with consistent personas
|
||||
|
||||
## Phase 3
|
||||
|
||||
1. Push notifications ("You haven't scrolled today" — optional)
|
||||
2. Topic difficulty progression
|
||||
3. Export: "What I learned this week" summary
|
||||
4. Chain/thread posts
|
||||
5. Share individual posts (screenshot or link)
|
||||
|
||||
---
|
||||
|
||||
## Context7 Required
|
||||
|
||||
Glitch MUST use Context7 for Next.js 16, Tailwind v4, Framer Motion, and ShadCN UI documentation before writing any code.
|
||||
|
||||
## Testing
|
||||
|
||||
- Hawk code review before merge
|
||||
- Mobile viewport testing (iPhone dimensions)
|
||||
- Feed should load and scroll smoothly with 100+ posts
|
||||
- AI generation should handle rate limits gracefully
|
||||
- SQLite should handle concurrent reads without blocking the UI
|
||||
|
||||
---
|
||||
|
||||
## File References
|
||||
- This spec: `data/tasks/learning-feed-spec.md`
|
||||
- Project directory: `projects/learning-feed/`
|
||||
- Standard stack: Next.js 16 + Tailwind v4 + Framer Motion + ShadCN + Lucide + TypeScript
|
||||
- Anthropic API key: available in environment (openclaw config)
|
||||
- Port: 3001
|
||||
- Systemd service: `learning-feed.service`
|
||||
Reference in New Issue
Block a user