Identify knowledge components

Identifying is the step where the pipeline reads your source and proposes what is worth writing up. Each command looks for one type of knowledge component and writes a list of candidates to your disk. Nothing reaches Fito yet — generating and pushing come after.

This page covers the three identify commands, their flags, and the list they write. It assumes you have something to read: a source tree or fetched documentation. Each command can also ingest for you on the way in.

The three commands

One command per component type, and each writes into its own folder:

Command	Looks for	Writes into by default
/fito-identify-domain-concepts	Concepts	./output/2-identify/domain_concepts/
/fito-identify-execution-facts	Execution facts	./output/2-identify/execution_facts/
/fito-identify-usage-scenarios	Usage scenarios	./output/2-identify/usage_scenarios/

Each command writes two files into its folder. For concepts they are domain_concepts.json, the candidate list the generate step reads, and domain_concepts.md, the same candidates as a summary you can read. The other two commands write the same pair, named execution_facts and usage_scenarios.

They share every flag. Run all three to cover a technology, or only the ones you need.

Before you begin

• A pi session in a working directory of your own, with Fito installed there. See Set up a working directory.
• An LLM provider configured in pi, and the pi-subagents package installed. Each command hands the reading to a worker persona, over that package, on your own model.
• The technology and the major line you are about to name, already provisioned. See Provision a technology.

You do not need to be logged in to Fito. Every call identify makes to the Fito server is a public read.

Identify candidates

1. Decide what the command reads. Pass --source <path> for a project on your disk, --fetch for a URL list, or nothing to read what an earlier step already ingested.

2. Run the command. For a tool:

   /fito-identify-domain-concepts Javalin --technology javalin --technology-version 7 --source ~/code/my-javalin-app

   For a practice, whose major line is Fito’s own numbering:

   /fito-identify-domain-concepts "Hexagonal Architecture" --technology hexagonal --technology-version 1

   The first argument is the subject’s name. --technology is its slug in Fito, and --technology-version is the major line every candidate must apply to.

3. Run the other two commands with the same arguments, if you want those types too. With --source, each one bundles the tree again, which is cheap.

4. Read the summary the command relays. It says how many candidates it found, and how many of them already exist in Fito.

5. Review the candidates in the .md summary before you generate. Generation writes up every new candidate unless you pick some — see Generate flags.

Confirm it worked: both files sit in the folder in the table above, and every candidate in the JSON list carries an already_exists value.

Flags

Flag	Required	Default	What it does
<tool-name>	Yes	—	The subject’s name, as the first argument. Quote a name with spaces
--technology <slug>	No	The name, lower-cased, spaces turned to dashes	The technology the candidates belong to
--technology-version <slug>	Yes	—	The major line the candidates apply to — 7 for a tool, 1 for a practice
--description "<text>"	No	—	A short account of what the subject does, to help the identifier find its domains
--source <path>	No	—	Bundle this source tree and read it. Wins over --fetch
--fetch	No	—	Run /fito-fetch-urls-content first
--urls <file>	No	urls.txt	The URL list for --fetch
--docs <path>	No	./output/1-ingest/extracted_links_content/	An already-ingested folder to read
--output <path>	No	The folder in the table above	The folder both files are written into. Their names never change

Pass --technology when the name and the slug differ

When you leave --technology off, the command derives the slug from the name. Javalin gives javalin, which is right. "Hexagonal Architecture" gives hexagonal-architecture, and the technology in Fito is hexagonal — so the command finds no such technology and stops.

Pass --technology whenever the name you type is not the slug.

Which identifier runs

The command reads the technology’s kind from Fito, and the kind picks the worker: a tool identifier or a practice identifier, one pair for each component type. No flag chooses it, and you never name one. Declare the technology, and the right identifier follows.

Where the input comes from

The command takes the first of these that applies:

1. --source — bundle the tree and read the bundle. --fetch is ignored.
2. --fetch — fetch the --urls list into the fetched-documentation folder, and read that.
3. --docs — read the folder it names, or the fetched-documentation folder when it names none.

Inside a case checkout, a command given none of the three offers to proceed with --source . once it has checked the checkout is yours to author. See Ingest a case you are authoring.

What the candidate list holds

Each candidate is checked against what Fito already holds for the declared major line, and it carries the answer:

• already_exists: true, with canonical_id naming the live component’s reference id — the idea is already written up.
• already_exists: false, with canonical_id: null — the idea is new.

The check is scoped to the major line. A component that is live only on another line reads as new, because on the line you declared it does not exist.

The generate step skips candidates that already exist, so this flag is what stops you writing the same component twice.

When the command stops

Message	What it means	What to do
Please provide the tool name. Usage: …	No first argument	Add the subject’s name
Please provide the Fito technology version the identified components apply to with --technology-version <slug> …	No major line	Add --technology-version
The Fito vocabulary holds no <slug> technology, so there is nothing to ground candidates against. …	The slug does not exist in Fito	Provision it, or correct a misspelt --technology
No source found at <docs-path>. …	Nothing was ingested, and the docs folder is empty or missing	Pass --source or --fetch, or point --docs at a filled folder

A misspelt slug is not a reason to provision. Provisioning the misspelling creates a second, independent technology beside the real one, and components pushed against the two land on different rows.

A server that is down is not a missing technology. When the lookup fails for any reason other than not-found — the server unreachable, a server error — the command reports that failure as it came and stops, without the provision-it-first message.

The same holds inside the identifier. When its check against Fito fails for a candidate, it stops and reports the failure, rather than marking the candidate new.

What’s next

• Generate and push components — write each new candidate up, and publish it.
• Knowledge components — what the three types are for.