Agent skill

questions-answers

Expert assistant for the Questions & Answers (Q&A) system in Raamattu Nyt. Develop, debug, and extend the full pipeline from search query classification through question upsert, AI answer generation, community answers, voting, admin moderation, and anchor questions. Use when (1) adding features to Q&A search results, (2) modifying question classification logic, (3) working on community answer forms or moderation, (4) changing AI answer generation or prompts, (5) editing admin Q&A management pages, (6) working with anchor questions or similar questions, (7) modifying votes/upvotes/downvotes, (8) fixing Q&A-related bugs, (9) extending answer types or display, (10) working on QuestionPage, QuestionsSearchSection, or AdminQuestionsPage.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/Spectaculous-Code/raamattu-nyt/tree/main/.claude/skills/questions-answers

SKILL.md

Questions & Answers System

Full-stack Q&A pipeline: search → classify → upsert → answer (AI/community/admin) → moderate → publish.

Architecture Overview

User search query
  → questionClassifier.ts (client-side)
  → upsert-question (edge fn: normalize, hash, classify, deduplicate)
  → QuestionsSearchSection renders:
      ├── Answers grouped by type (bullet → editorial → community → AI)
      ├── CommunityAnswerForm (auth-gated)
      ├── QuestionConsentBlock (AI generation / human request)
      ├── AnchorQuestionsSection (topic-linked curated Q&A)
      └── SimilarQuestionsSection (trigram similarity)

Key Files

Edge Functions

Function Path Purpose
upsert-question supabase/functions/upsert-question/ Normalize, classify, upsert, find similar
generate-ai-answer supabase/functions/generate-ai-answer/ AI answer via Claude (paid, quota-checked)
submit-community-answer supabase/functions/submit-community-answer/ User-submitted answer (free, needs admin approval)
vote supabase/functions/vote/ +1/-1 voting on questions/answers

Hooks (apps/raamattu-nyt/src/hooks/)

Hook File Purpose
useUpsertQuestion useQuestions.ts Mutation: upsert question via edge fn
useGenerateAiAnswer useQuestions.ts Mutation: generate AI answer (quota-checked)
useSubmitCommunityAnswer useQuestions.ts Mutation: submit community answer
useVote useQuestions.ts Mutation: vote on question/answer
usePublishedQuestion useQuestions.ts Query: single published question by slug
useQuestionAnswers useQuestions.ts Query: published answers for question
useAdminQuestions useQuestions.ts Query: all questions with answer stats
useAdminAnswers useQuestions.ts Query: all answers (including unpublished)
useAnchorQuestions useAnchorQuestions.ts Query: anchor Q&A grouped by topic

Components (apps/raamattu-nyt/src/components/search/)

Component Purpose
QuestionsSearchSection Main Q&A display in search results
QuestionConsentBlock AI answer / human request consent
CommunityAnswerForm User answer submission form
SimilarQuestionsSection Trigram-similar questions
AnchorQuestionsSection Topic-linked curated Q&A

Pages

Page Route Purpose
QuestionPage.tsx /kysymys/:slug Public single question view + admin tools
AdminQuestionsPage.tsx /ohjaamo/questions Full admin Q&A dashboard
PremiumQuestionsPage.tsx /premium/questions Public questions browsing

Core Libraries

File Purpose
src/lib/questionClassifier.ts Client-side question detection (Finnish)

Database Schema (bible_schema)

For full schema details: See references/schema.md

Tables

  • questions — Normalized questions with classification, status, voting
  • answers — Answers with author_type, rich content, key_verses, topics, strongs_refs
  • votes — User votes (+1/-1) on questions/answers (unique per user)
  • topic_anchor_questions — Links questions as anchor Q&A for topics

Answer Author Types

Type Created by Published by default?
bullet Admin Yes
admin Admin Yes
system Import/seed Yes
ai Edge function No (needs admin review)
community Authenticated user No (needs admin approval)

Question Status Flow

draft → needs_review → approved → published
                    └→ rejected

RLS Summary

  • Anon/Auth: Read published questions + published non-hidden answers
  • Auth: Read own questions + own community answers, insert votes, submit community answers
  • Admin: Full CRUD on all questions, answers, votes

Common Patterns

Add new answer type

  1. Add CHECK constraint value in migration
  2. Update AnswerData interface in QuestionsSearchSection.tsx
  3. Update Answer type in useQuestions.ts
  4. Add rendering logic in renderAnswerCard
  5. Update admin management in AdminQuestionsPage.tsx

Add new question classification

  1. Update classifier patterns in questionClassifier.ts
  2. Mirror logic in upsert-question edge function
  3. Update CHECK constraint if new DB value needed
  4. Add UI handling in QuestionsSearchSection

Modify AI answer generation

  1. Edit prompt template via ai-prompt-manager skill
  2. Edge function: generate-ai-answer/index.ts
  3. Output validation: excerpt, key_verses, topics, strongs_refs, related_questions
  4. Model/vendor configured via ai_feature_bindings table

Add feature to community answers

  1. Edge function: submit-community-answer/index.ts
  2. Hook: useSubmitCommunityAnswer in useQuestions.ts
  3. Form: CommunityAnswerForm.tsx (search) or inline in QuestionPage.tsx
  4. Admin tab: "Yhteisövastaukset" in AdminQuestionsPage.tsx

Shared UI Components

  • BibleReferencePickerPopover — Verse picker popover (used across 6 files)
  • SafeTextarea — Input with XSS protection, markup detection
  • RichContentRenderer — Renders body_html from rich editor
  • VerseContentCard — Displays verse reference with content
  • FeedbackThumbs / FeedbackText — Answer feedback (AI answers)

References

  • Full schema + RLS policies: See references/schema.md

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Spectaculous-Code/raamattu-nyt

docs-updater

Expert assistant for keeping documentation synchronized with code changes in the KR92 Bible Voice project. Use when updating API docs, maintaining architecture diagrams, syncing README, updating CLAUDE.MD, or generating documentation from code.

0 0
Explore
Spectaculous-Code/raamattu-nyt

ai-prompt-manager

Expert assistant for managing AI prompts, features, and configuration in the KR92 Bible Voice AI system. Use when creating AI prompts, configuring AI features, managing prompt versions, setting up AI bindings, or working with AI pricing and models.

0 0
Explore
Spectaculous-Code/raamattu-nyt

performance-auditor

Expert assistant for monitoring and optimizing performance in the KR92 Bible Voice project. Use when analyzing query performance, optimizing database indexes, reviewing React Query caching, monitoring AI call costs, or identifying N+1 queries.

0 0
Explore
Spectaculous-Code/raamattu-nyt

edge-function-generator

Expert assistant for creating and maintaining Supabase Edge Functions for the KR92 Bible Voice project. Use when creating Edge Functions, setting up CORS, integrating shared modules, adding JWT validation, or configuring environment variables.

0 0
Explore
Spectaculous-Code/raamattu-nyt

admin-panel-builder

Expert assistant for creating and maintaining admin panel pages in the KR92 Bible Voice project. Use when creating admin pages, building admin components, integrating with admin navigation, or adding admin features.

0 0
Explore
Spectaculous-Code/raamattu-nyt

lint-fixer

Expert assistant for analyzing and fixing linting and formatting issues in the KR92 Bible Voice project using Biome and TypeScript. Use when fixing lint errors, resolving TypeScript issues, applying code formatting, or reviewing code quality.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results