Facts
The antidote to fluffy specs.
35 followers
The antidote to fluffy specs.
35 followers
Your project has 48 facts, 31 of them implemented: code-backed, verified by command. 12 are specs your agent is working through. 5 are rough drafts you'll refine later. You know all of this because you ran facts check.
Free
Launch Team / Built With
AWS Startup AdvisorPersonalized AWS guidance that meets you where you’re already building
Promoted
How your facts can help me improve my coding?
@serge_cherny thanks for the question!
Facts is a CLI + Skills for your coding agent. It replaces your spec system with a set of atomic simple assertions about desired project state, the skills and CLI allow the agent to maintain it and develop the project based on them.
For example, for a new project you would:
Install the av/facts skill, ask agent to "init facts in this project", the agent will install everything else for you
Ask the agent "Let's develop X, here are things that important: A, B, C", the agent will create a fact sheet and ask you for clarifications where needed
Use `/facts-implement` to implement the entire project - it pairs very well with subagents
For existing project:
Install the skill, ask agent to init the facts in the project
The agent will run `/facts-discover` skill which will map your existing project state to a facts sheet
From there, you can add/edit facts and ask your agent to work on them, it should handle the rest :)
Compared to specs, facts are:
Terse - you don't waster your time reading fluff, agent doesn't waste tokens writing it
Have formal workflow/spec behind them - there's only a single way to write/maintain a fact sheet and your agent will know exactly how to use it. Agent of your colleague will follow identical process too.
QoLs - maintaining fact sheets, diffing for internal inconsistencies, mapping code to fact sheets and finally implementing a project based on one
The project itself is built with this approach, so you can see an example here:
https://github.com/av/facts/blob/main/.facts
"48 facts, 31 implemented, 12 in progress, 5 drafts" — that's a perfect framing of what most engineering specs lose the moment they leave Notion. We have the same fluff problem in financial modeling. "DSCR target 1.30x, sculpted debt, partnership flip after Year 6" sounds rigorous on a slide and turns out to be three different things to three reviewers. The fix is the same: facts that are code-backed and verifiable from the model itself, not prose that ages out. That's the discipline I tried to bake into my project finance and valuation templates on Eloquens — testable assumptions, not narrative. Curious how Facts handles spec drift after a fact is verified — do you flag re-verification when the underlying code changes, or only on commit?
Hi PH, I'm absolutely blown away by the response to this small project, thank you!
As a token of my gratitude, I want to share the workflow I used for the promo video:
1. I start all such projects with a definition of design/visual language. This time it was around PS1-era aesthetic. Initial designs were nothing like the final, but it clicked eventually when I suggested to use Spyro as a reference.
Tip: there are websites to preview color palettes in realistic settings via URL, this way your agent can share ideas with you very quickly.
2. In my lifeos, I maintain a few content templates, one of them is for a motion graphics script creation, I use it to create a first draft of the script.
Tip: I usually start and center the script around a single central idea or state the viewer should receive. After initial version is done, I assemble initial video, just to see where it lands.
3. Adjusting the visual style and look'n'feel until it looks as intended. In this instance, for example, I've tweaked leading fonts, the specific look'n'feel of rendering, and added two different color palettes for text and visuals so that they don't overlap. After this step the visual part is locked and I proceed iterating on the content.
4. This is just going through all scenes one-by-one and verifying that they make sense. One easy tip is to always ask agent to redo the scenes considering viewer has zero context about the project or its purpose in mind as well as make every scene ~5s longer than you think it needs to be.
As a bonus, with the visual/desing language codified - you can later proceed creating the content for the same project without loosing the identity, all in agentic-friendly way :)
Thanks again!