Skip to content

docs: the plan for splitting "what the content is" from "what the machine does" - #126

Merged
wu908 merged 1 commit into
mainfrom
docs/intent-taxonomy-migration-plan
Sep 16, 2026
Merged

wu908 merged 1 commit into
mainfrom
docs/intent-taxonomy-migration-plan

Conversation

@wu908

@wu908 wu908 commented Sep 16, 2026

Copy link
Copy Markdown
Owner

Answering the creator's three questions — why three values, doesn't that constrain the content, doesn't it constrain what the AI produces — with the conclusion that the enum is not the problem: one field is doing two jobs.

Why the split, not the delete

Machine behaviour needs a comparable finite key: routing, which judgment fields are required, which signals are watched, and — verified, not assumed — which learned rules apply at all:

content_genome.py:147
if query["content_intent"] and applicability["intent"] != query["content_intent"]:
    continue        # this rule does not apply to this piece

So the field is load-bearing beyond cosmetics: before #124 a piece of text was judged solve, which meant experience distilled for share pieces was silently not used. "What is this content" needs to be open, because the creator should never pick from three and the AI should be able to name any shape it sees. Deleting the enum pushes interpretation into 12 files; splitting it keeps the machine's key finite and lets the naming be free.

The plan (additive, staged, reversible, production usable throughout)

  1. Add content_form (open, AI-named) as pure plumbing — no visual change at all.
  2. Show the AI's name, demote the three values to the behaviour key — this is the step with visible change; the confirm step's copy becomes 「这篇要读者拿走什么」.
  3. Rename the behaviour key in the rubric so it stops reading as a content category.
  4. Only if a fourth behaviour appears, widen the six CHECK constraints in one migration — explicitly not for a new content shape.

Inventory is measured, not estimated

references 139 across 12 files (content_genome 30, content_opportunity 17, intent_actions 11)
tables carrying the CHECK six (020×2, 023, 025, 026, 027; deliverables nullable)
user-visible render sites five
E2E assertions on intent labels none — so the copy carries less risk than feared

Also records the migration trap that has now bitten twice (any new column on content_projects must be added to the 043 rebuild DDL constant), and the acceptance criteria including one test to keep content_form out of routing.

…hine does"

Answering the creator's three questions — why three values, doesn't that
constrain the content, doesn't it constrain what the AI produces — with the
conclusion that the enum is not the problem: one field is doing two jobs.

Machine behaviour (routing, which judgment fields are required, which signals
are watched, and — verified — which learned rules apply at all:
`content_genome.py:147` skips rules whose applicability intent differs) needs a
comparable finite key. "What is this content" needs to be open, because the
creator should never pick from three, and the AI should be able to name any
shape it sees. Those are different requirements on one field.

So deleting the enum is the wrong fix; splitting it is the right one. The plan
is additive and staged, each step its own PR, each reversible, production usable
throughout:

1. add `content_form` (open, AI-named) as plumbing — no visual change;
2. make the UI show the AI's name and demote the three values to the behaviour
   key (this is the step with visible change);
3. rename the behaviour key in the rubric so it stops reading as a content
   category;
4. only if a fourth *behaviour* ever appears, widen the six CHECK constraints
   in one migration — explicitly not for a new content shape.

The inventory is measured, not estimated: 139 references across 12 files, six
tables carrying the CHECK, five user-visible render sites, and — usefully —
no E2E assertion on any intent label, so the copy carries less risk than feared.
@wu908
wu908 merged commit 27b03bf into main Sep 16, 2026
2 checks passed
@wu908
wu908 deleted the docs/intent-taxonomy-migration-plan branch September 16, 2026 06:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant