feat: add contribution readiness assistant

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>

Author: arnabnandy7

README.md

@@ -9,9 +9,11 @@
 - Filters by explicit experience, contribution-type, and small-scope signals
 - Scores repository health from maintenance and contributor-activity signals
 - Summarizes maintainer responsiveness from bounded recent contribution samples
+- Classifies contribution readiness from cached community documentation and activity signals
 - Sorts and ranks results using issue quality and repository health
 - Keeps successful searches in shareable, browser-navigable URLs
 - Identifies when optional GitHub enrichment is incomplete
+- Links repository contribution documentation from expandable issue checklists
 - Surfaces trending opportunities by recent activity, discussion, stars, and repository health
 - Supports reusable saved searches without requiring an account
 - Adds GitHub sign-in for cloud-backed saved searches that survive cleared browser storage

db/migrations/0013_contribution_readiness.sql

@@ -0,0 +1 @@
+ALTER TABLE "saved_search" ADD COLUMN "readiness" text DEFAULT 'any' NOT NULL;

doc/architecture.md

@@ -70,6 +70,16 @@ flowchart LR
 
 Candidate issues are enriched where possible with repository metadata, recent discussion, assignment state, linked pull requests, and Hacktoberfest signals. Repository health uses recent pushes, open issue and pull-request activity, stars, forks, and issue-tracker availability to distinguish active, moderate, and stale projects. The health score contributes a small optional boost to issue quality ranking and is shown directly on issue cards. The application ranks the enriched results for contributor relevance and returns paginated results to the browser.
 
+Contribution readiness combines the existing repository health, maintainer
+responsiveness, assignment, and discussion signals with GitHub's community
+profile. Community-profile requests are limited to 12 repositories per search
+and cached for six hours. The profile supplies README, contributing guide,
+license, code-of-conduct, issue-template, and pull-request-template links.
+Issue cards show an explainable readiness status and expandable checklist.
+Unavailable profiles produce `Unknown` rather than a zero score; inactive,
+claimed, and poorly documented opportunities remain distinguishable from issues
+that are ready to start or should be discussed with maintainers first.
+
 Maintainer responsiveness remains separate from repository health. For at most 12
 candidate repositories per search, a cached six-hour GitHub GraphQL request samples
 up to 20 recently updated issues and pull requests from the previous 90 days. The
@@ -100,6 +110,7 @@ Search filters currently include:
 - Documentation, tests, bug fix, or feature contribution type
 - All scopes or small scope
 - Any, responsive, variable, slow, or unknown maintainer responsiveness
+- Any readiness or Ready to start
 
 Experience, contribution type, and scope classifications use explicit issue
 labels and structured issue-template fields. Results show the signals that
@@ -249,6 +260,7 @@ erDiagram
     text contribution_type
     text scope
     text responsiveness
+    text readiness
   }
 
   OPPORTUNITY {
@@ -370,6 +382,8 @@ contributing signals beside each repository. Weekly recommendations display the
 same quality and repository-health scores used to rank results in the portal.
 Repository alerts enrich their newest issues with repository health and the same
 quality formula before adding the repository responsiveness boost.
+Saved-search recommendations and weekly digest searches retain the selected
+contribution-readiness filter, and weekly issue summaries include readiness.
 Saved-search recommendations, repository alerts, repository metadata, and
 post-delivery persistence run concurrently where independent so SMTP delivery is
 not delayed by avoidable serial network or database round trips.

doc/contributing.md

@@ -35,7 +35,10 @@ The test suite uses Vitest. Coverage thresholds are configured in `vitest.config
 
 ## Database changes
 
-Database changes must update both the Drizzle schema and a new ordered SQL migration. Migrations may be public because they describe structure, not credentials. Never include tokens, secrets, or production records in them.
+Database changes must update the Drizzle schema, architecture documentation,
+and a new ordered SQL migration. Migrations may be public because they describe
+structure, not credentials. Never include tokens, secrets, or production records
+in them.
 
 ## Testing guidance
 

doc/setup.md

@@ -52,6 +52,7 @@ Run the SQL migrations in filename order against the Turso database:
 10. `db/migrations/0010_maintainer_responsiveness.sql`
 11. `db/migrations/0011_issue_feedback.sql`
 12. `db/migrations/0012_opportunity_workflow.sql`
+13. `db/migrations/0013_contribution_readiness.sql`
 
 The first migration creates Better Auth's user, session, account, and verification tables. The second creates user-owned saved searches. Migration files intentionally contain structure only—never credentials or production data.
 
@@ -78,6 +79,8 @@ searches. Existing records default to unrestricted responsiveness.
 The eleventh stores dismissed recommendation feedback and repositories hidden
 by a user. The twelfth adds private state, note, follow-up date, and workflow
 activity fields to saved opportunities; existing opportunities begin in Saved.
+The thirteenth adds the contribution-readiness preference to cloud saved searches;
+existing records continue to include every readiness status.
 
 ## GitHub OAuth
 

src/app/api/saved-searches/route.ts

@@ -43,6 +43,7 @@ async function listSavedSearches(userId: string): Promise<SavedSearch[]> {
     contributionType: row.contributionType,
     scope: row.scope,
     responsiveness: row.responsiveness,
+    readiness: row.readiness,
     createdAt: row.createdAt.toISOString(),
   }));
 }

src/app/api/search/route.ts

@@ -38,6 +38,7 @@ export async function GET(request: Request) {
       contributionType: searchParams.get("contributionType"),
       scope: searchParams.get("scope"),
       responsiveness: searchParams.get("responsiveness"),
+      readiness: searchParams.get("readiness"),
       page,
     });
 

src/features/issues/components/issue-card.tsx

@@ -30,11 +30,43 @@ import {
 import { compactNumber, relativeDate } from "@/features/issues/lib/format";
 import { getResponsivenessBoost } from "@/features/issues/lib/repository-responsiveness";
 import type {
+  ContributionReadinessStatus,
   Issue,
   RepositoryHealth,
   RepositoryResponsiveness,
 } from "@/features/issues/types/search";
 
+const READINESS_LABELS: Record<ContributionReadinessStatus, string> = {
+  ready: "Ready to start",
+  ask: "Ask before starting",
+  claimed: "Possibly claimed",
+  poorlyDocumented: "Poorly documented",
+  inactive: "Repository inactive",
+  unknown: "Readiness unknown",
+};
+
+const DOCUMENTATION_LABELS = {
+  readme: "README",
+  contributing: "Contributing guide",
+  license: "License",
+  codeOfConduct: "Code of conduct",
+  issueTemplate: "Issue template",
+  pullRequestTemplate: "Pull-request template",
+} as const;
+
+function getReadinessClassName(status: ContributionReadinessStatus) {
+  if (status === "ready") {
+    return "border-emerald-500/20 bg-emerald-500/10 text-emerald-700 dark:text-emerald-400";
+  }
+  if (status === "ask" || status === "poorlyDocumented" || status === "claimed") {
+    return "border-amber-500/20 bg-amber-500/10 text-amber-700 dark:text-amber-400";
+  }
+  if (status === "inactive") {
+    return "border-rose-500/20 bg-rose-500/10 text-rose-700 dark:text-rose-400";
+  }
+  return "";
+}
+
 function getQualityBadgeClassName(qualityScore: number) {
   if (qualityScore >= 70) {
     return "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400 border-emerald-500/20";
@@ -220,6 +252,14 @@ function IssueBadges({ issue }: Readonly<{ issue: Issue }>) {
 
   return (
     <div className="flex flex-wrap items-center gap-2">
+      {issue.contributionReadiness ? (
+        <Badge
+          variant="outline"
+          className={getReadinessClassName(issue.contributionReadiness.status)}
+        >
+          {READINESS_LABELS[issue.contributionReadiness.status]}
+        </Badge>
+      ) : null}
       <RepositoryHealthTooltip issue={issue} />
       <ResponsivenessTooltip issue={issue} />
       {issue.hacktoberfest ? (
@@ -291,6 +331,37 @@ export function IssueCard({
         </CardTitle>
       </CardHeader>
       <CardContent className="space-y-4">
+        {issue.contributionReadiness ? (
+          <details className="rounded-lg border px-3 py-2 text-sm">
+            <summary className="cursor-pointer font-medium">
+              Contribution readiness checklist
+              {issue.contributionReadiness.score === null
+                ? ""
+                : ` · ${issue.contributionReadiness.score}/100`}
+            </summary>
+            <ul className="mt-2 list-disc space-y-1 pl-5 text-muted-foreground">
+              {issue.contributionReadiness.signals.map((signal) => (
+                <li key={signal}>{signal}</li>
+              ))}
+            </ul>
+            <div className="mt-2 flex flex-wrap gap-x-3 gap-y-1">
+              {Object.entries(issue.contributionReadiness.documentation).map(
+                ([name, url]) =>
+                  url ? (
+                    <a
+                      key={name}
+                      href={url}
+                      target="_blank"
+                      rel="noreferrer"
+                      className="text-primary underline-offset-4 hover:underline"
+                    >
+                      {DOCUMENTATION_LABELS[name as keyof typeof DOCUMENTATION_LABELS]}
+                    </a>
+                  ) : null,
+              )}
+            </div>
+          </details>
+        ) : null}
         {issue.classification?.signals.length ? (
           <div className="flex flex-wrap gap-2" aria-label="Classification signals">
             {issue.classification.signals.map((signal) => (

src/features/issues/components/issue-finder.tsx

@@ -61,6 +61,7 @@ import {
   HACKTOBERFEST_OPTIONS,
   LABEL_OPTIONS,
   LINKED_PR_OPTIONS,
+  READINESS_OPTIONS,
   RESPONSIVENESS_OPTIONS,
   SORT_OPTIONS,
   SCOPE_OPTIONS,
@@ -92,6 +93,7 @@ type SearchFilters = {
   contributionType: string;
   scope: string;
   responsiveness: string;
+  readiness: string;
 };
 
 const DEFAULT_SEARCH_FILTERS: SearchFilters = {
@@ -104,6 +106,7 @@ const DEFAULT_SEARCH_FILTERS: SearchFilters = {
   contributionType: "any",
   scope: "any",
   responsiveness: "any",
+  readiness: "any",
 };
 
 function getSupportedValue(
@@ -146,6 +149,11 @@ function getSearchFilters(search: string): SearchFilters | null {
       RESPONSIVENESS_OPTIONS,
       "any",
     ),
+    readiness: getSupportedValue(
+      params.get("readiness"),
+      READINESS_OPTIONS,
+      "any",
+    ),
   };
 }
 
@@ -160,6 +168,7 @@ function createSearchParams(filters: SearchFilters, page?: number) {
     contributionType: filters.contributionType,
     scope: filters.scope,
     responsiveness: filters.responsiveness,
+    readiness: filters.readiness,
     ...(page ? { page: String(page) } : {}),
   });
 }
@@ -173,6 +182,14 @@ function leastAvailable(
     : second;
 }
 
+function leastAvailableOptional(
+  first?: EnrichmentAvailability,
+  second?: EnrichmentAvailability,
+) {
+  if (!first || !second) return first ?? second;
+  return leastAvailable(first, second);
+}
+
 const ENRICHMENT_PRIORITY: Record<EnrichmentAvailability, number> = {
   complete: 0,
   partial: 1,
@@ -198,6 +215,10 @@ function mergeEnrichment(
       current.linkedPullRequests,
       next.linkedPullRequests,
     ),
+    communityProfile: leastAvailableOptional(
+      current.communityProfile,
+      next.communityProfile,
+    ),
   };
 }
 
@@ -328,7 +349,11 @@ function EnrichmentNotice({ data }: Readonly<{ data: SearchResponse | null }>) {
     ["repository metadata", data.enrichment.repositoryMetadata],
     ["discussion analysis", data.enrichment.discussionAnalysis],
     ["linked pull requests", data.enrichment.linkedPullRequests],
-  ].filter(([, availability]) => availability !== "complete");
+    ["community profiles", data.enrichment.communityProfile],
+  ].filter(
+    ([, availability]) =>
+      availability !== undefined && availability !== "complete",
+  );
 
   if (unavailableSignals.length === 0) return null;
 
@@ -732,6 +757,7 @@ export function IssueFinder() {
   const [responsiveness, setResponsiveness] = useState(
     DEFAULT_SEARCH_FILTERS.responsiveness,
   );
+  const [readiness, setReadiness] = useState(DEFAULT_SEARCH_FILTERS.readiness);
   const [data, setData] = useState<SearchResponse | null>(null);
   const [issues, setIssues] = useState<Issue[]>([]);
   const [page, setPage] = useState(1);
@@ -775,6 +801,7 @@ export function IssueFinder() {
         setContributionType(DEFAULT_SEARCH_FILTERS.contributionType);
         setScope(DEFAULT_SEARCH_FILTERS.scope);
         setResponsiveness(DEFAULT_SEARCH_FILTERS.responsiveness);
+        setReadiness(DEFAULT_SEARCH_FILTERS.readiness);
         setData(null);
         setIssues([]);
         setError(null);
@@ -792,6 +819,7 @@ export function IssueFinder() {
       setContributionType(linkedSearch.contributionType);
       setScope(linkedSearch.scope);
       setResponsiveness(linkedSearch.responsiveness);
+      setReadiness(linkedSearch.readiness);
       void searchIssues(undefined, linkedSearch, false);
     }
 
@@ -945,6 +973,10 @@ export function IssueFinder() {
       RESPONSIVENESS_OPTIONS[0],
     [responsiveness],
   );
+  const selectedReadiness = useMemo(
+    () => READINESS_OPTIONS.find((item) => item.value === readiness) ?? READINESS_OPTIONS[0],
+    [readiness],
+  );
 
   const hasMore = useMemo(() => {
     if (!data) return false;
@@ -975,6 +1007,7 @@ export function IssueFinder() {
         contributionType,
         scope,
         responsiveness,
+        readiness,
       });
 
       setSavedSearches((current) => [...current, savedSearch]);
@@ -1029,6 +1062,7 @@ export function IssueFinder() {
     setContributionType(savedSearch.contributionType ?? "any");
     setScope(savedSearch.scope ?? "any");
     setResponsiveness(savedSearch.responsiveness ?? "any");
+    setReadiness(savedSearch.readiness ?? "any");
 
     void searchIssues(undefined, {
       tech: savedSearch.tech,
@@ -1040,6 +1074,7 @@ export function IssueFinder() {
       contributionType: savedSearch.contributionType ?? "any",
       scope: savedSearch.scope ?? "any",
       responsiveness: savedSearch.responsiveness ?? "any",
+      readiness: savedSearch.readiness ?? "any",
     });
   }
 
@@ -1122,6 +1157,7 @@ export function IssueFinder() {
     const searchScope = searchOverride?.scope ?? scope;
     const searchResponsiveness =
       searchOverride?.responsiveness ?? responsiveness;
+    const searchReadiness = searchOverride?.readiness ?? readiness;
 
     if (!searchTech.trim()) {
       setError("Enter a technology to search.");
@@ -1145,6 +1181,7 @@ export function IssueFinder() {
       contributionType: searchContributionType,
       scope: searchScope,
       responsiveness: searchResponsiveness,
+      readiness: searchReadiness,
     });
     const requestId = ++searchRequestId.current;
 
@@ -1204,6 +1241,7 @@ export function IssueFinder() {
         contributionType,
         scope,
         responsiveness,
+        readiness,
       },
       nextPage,
     );
@@ -1429,6 +1467,23 @@ export function IssueFinder() {
                 </SelectContent>
               </Select>
 
+              <Select value={readiness} onValueChange={setReadiness}>
+                <SelectTrigger
+                  className="h-11 w-full"
+                  size="lg"
+                  aria-label="Contribution readiness filter"
+                >
+                  <SelectValue>{selectedReadiness.label}</SelectValue>
+                </SelectTrigger>
+                <SelectContent>
+                  {READINESS_OPTIONS.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+
               <Button
                 type="submit"
                 className="h-11 w-full gap-2 sm:col-span-2 lg:col-span-1"