How Your Brief Works

This document explains exactly how your daily Brief works. Every claim includes the actual source code. Anyone can verify these claims against the public repository.

The Brief is defined in src/modules/brief/brief.service.ts.

The Three Layers

Your Brief draws content from three sources. You control how much of each you see.

By default, the balance is 40% Circle, 40% Field, 20% Horizon. You can change these weights at any time. The only constraint — the three must add up to 100%:

// brief.service.ts, line 97
const total = merged.circleWeight + merged.fieldWeight + merged.horizonWeight;
if (total !== 100) {
  throw new ValidationError("Circle, Field, and Horizon weights must sum to 100");
}

Circle — People You Follow

Circle shows posts from people you follow. Nothing else.

Here is the complete Circle query. This is the entire algorithm — one database query, newest first, no scoring:

// brief.service.ts, lines 236–256
const circlePosts = await db
  .select({
    post: posts,
    author: {
      userId: userProfiles.userId,
      displayName: userProfiles.displayName,
      username: userProfiles.username,
      headline: userProfiles.headline,
      avatarUrl: userProfiles.avatarUrl,
    },
  })
  .from(posts)
  .leftJoin(userProfiles, eq(posts.authorId, userProfiles.userId))
  .where(
    and(
      eq(posts.isDeleted, false),
      inArray(posts.authorId, followedUserIds),
    ),
  )
  .orderBy(desc(posts.createdAt))
  .limit(circleCount);

The ordering is desc(posts.createdAt) — newest first, always. There is no scoring. There is no re-ranking. There is no "you might also like." The most recent post from someone you follow appears first.

Even if you cannot read TypeScript, you can see: there is no score variable, no weight calculation, no model.predict(). One query. Sort by date. Done.

Field — Your Declared Interests

Field shows posts matching your skills and Active Season — things you told us you care about.

The key word is declared. Field matches on what you explicitly put on your profile, not what you clicked on, not what you lingered on, not what an algorithm inferred from your behavior.

The matching logic finds topics whose slugs match your skill categories, then gets posts tagged with those topics:

// brief.service.ts, lines 337–354
fieldPosts = await db
  .select({
    post: posts,
    author: { ... },
  })
  .from(posts)
  .leftJoin(userProfiles, eq(posts.authorId, userProfiles.userId))
  .where(and(...baseConditions, inArray(posts.topicId, matchingTopicIds)))
  .orderBy(desc(posts.createdAt))
  .limit(fieldCount);

Again: orderBy(desc(posts.createdAt)). Newest first. No engagement scoring.

Each Field item tells you why it appeared:

// brief.service.ts, lines 383–385
reason: skillNames.length > 0
  ? `Relevant to your fields: ${skillNames.slice(0, 3).join(", ")}`
  : undefined,

You can always trace the reason back to something you chose to declare.

Horizon — Outside Your Bubble

Horizon shows a small number of posts from outside your follow graph and skill matches. Its purpose is serendipity — showing you things you wouldn't otherwise encounter.

// brief.service.ts, lines 403–418
const horizonPosts = await db
  .select({
    post: posts,
    author: { ... },
  })
  .from(posts)
  .leftJoin(userProfiles, eq(posts.authorId, userProfiles.userId))
  .where(and(...horizonConditions))
  .orderBy(desc(posts.createdAt))
  .limit(Math.min(horizonCount, 15)) // cap at 15 per spec

Same pattern: orderBy(desc(posts.createdAt)). Capped at 15 items.

Every Horizon item includes a reason label. The reason is generated by deriveHorizonReason(), which checks three things in order:

// brief.service.ts, lines 150–181
function deriveHorizonReason(post, trustedAuthorIds, keywords): string {
  // 1. Quality signals — practical, insightful, well_sourced
  if (counts) {
    const qualitySignals = (counts["practical"] ?? 0)
      + (counts["insightful"] ?? 0) + (counts["well_sourced"] ?? 0);
    if (qualitySignals >= 2) {
      return "Found practical by professionals in this area";
    }
  }
 
  // 2. Trust graph — author followed by someone you follow
  if (trustedAuthorIds.has(post.authorId)) {
    return "Endorsed by someone in your network";
  }
 
  // 3. Keyword overlap — matches your skills or seasons
  if (keywords.length > 0) {
    const text = `${post.title ?? ""} ${post.body}`.toLowerCase();
    const matched = keywords.find((kw) => text.includes(kw));
    if (matched) {
      return `Related to your focus: ${matched}`;
    }
  }
 
  return "Outside your usual reading";
}

There is no opaque relevance score. The reason is always visible. And critically — these reasons are labels only. They do not affect the ordering. Horizon is always chronological.

Exploratory Mode

You can switch your Brief to "exploratory" density mode. This shifts 15 percentage points from Circle and Field into Horizon:

// brief.service.ts, lines 207–213
if (config.densityMode === "exploratory") {
  const horizonBoost = 15;
  const circleReduction = Math.round(
    horizonBoost * (circleWeight / (circleWeight + fieldWeight || 1))
  );
  const fieldReduction = horizonBoost - circleReduction;
  circleWeight = Math.max(5, circleWeight - circleReduction);
  fieldWeight = Math.max(5, fieldWeight - fieldReduction);
}

The redistribution is proportional. Both Circle and Field keep at least 5% each.

Positioned Question

At the bottom of your Brief, you may see "One question you're positioned to answer" — an unanswered question matching your declared skills or Active Season focus.

// brief.service.ts, lines 536–546
const results = await db
  .select({ post: posts, author: { ... } })
  .from(posts)
  .leftJoin(userProfiles, eq(posts.authorId, userProfiles.userId))
  .where(
    and(
      eq(posts.isDeleted, false),
      eq(posts.postType, "question"),
      eq(posts.isAnswered, false),
      sql`${posts.authorId} != ${userId}`,
      sql`${posts.searchVector} @@ to_tsquery('english', ${tsqueryStr})`,
    ),
  )
  .orderBy(desc(posts.createdAt))
  .limit(1);

PostgreSQL full-text search. Newest matching question first. No popularity ranking.

What the Brief Does NOT Do

This section is the most important part of this document. Absence is harder to prove than presence, but these are verifiable facts:

Does not track what you click on. There is no click_count column in any database table. There is no click event. The codebase contains zero references to click tracking.

Does not measure how long you spend reading. There is no time_spent, view_duration, or dwell_time column. There is no timer. The Brief does not know whether you read a post for one second or one hour.

Does not use any machine learning model. There is no TensorFlow, no PyTorch, no scikit-learn, no ML library of any kind imported anywhere in the codebase. You can verify this by running:

npm run transparency:negative-checks

Does not boost content based on reactions. Signal counts (practical, insightful, etc.) are visible on posts, but they do not influence Circle or Field ordering. Horizon uses them only for the reason label — and even there, the ordering is still chronological.

Does not suppress content based on low engagement. A post with zero signals appears in exactly the same position as a post with a hundred signals, as long as it was posted at the same time.

Does not personalize beyond your explicit choices. The only personalization inputs are: (1) who you follow, (2) what skills you declared, (3) what Active Season you set, (4) your layer weight preferences. All of these are things you consciously chose. None of them are inferred.

Does not run A/B tests. There is no A/B testing framework. Every user sees the same Brief logic. There are no experimental groups, no holdout groups, no shadow features.

How to Verify

Every claim in this document can be verified:

1. Read the source code. The file is src/modules/brief/brief.service.ts in the public repository. The actual code is shown above — compare it to the repo.

2. Run the negative checks. Clone the repo and run npm run transparency:negative-checks. This greps the entire codebase for tracking, ML, analytics, and engagement scoring patterns.

3. Check the git history. Every change to the Brief is tracked with full blame history. You can see exactly when each line was added and by whom.

4. Search for yourself. If you suspect we're hiding something, search the codebase for any term you're concerned about: engagement, click, tracking, model, tensorflow, analytics. The code is public.

This document will be updated whenever the Brief logic changes. The modification date at the top tells you when it was last reviewed.