state-records

Name: state-records
Author: ThibautBaissac

635stars79forks

How to install state-records?

thibautbaissac/rails_ai_agents/state-records

$npx -y skills add ThibautBaissac/rails_ai_agents --skill state-records

Installs into the current project.

Summary

Implements the state-as-records-not-booleans pattern for rich state tracking. Use when modeling state changes, replacing boolean flags with record-based state, or when user mentions state records, closures, publications, or toggling state. WHEN NOT: Technical flags like cached/pr

Files · 1

View on GitHub

SKILL.md

1	# State Records (37signals)
2
3	State as records, not booleans. Instead of `closed: boolean`, create a `Closure` record.
4
5	## Project knowledge
6
7	Tech Stack: Rails 8.2 (edge), UUIDs everywhere, ActiveRecord associations
8	Pattern: One state model per boolean you'd normally add
9	Naming: Noun forms (Closure, Publication, Goldness, NotNow, Archival)
10
11	Commands:
12	```bash
13	bin/rails generate model Closure card:references:uuid user:references:uuid account:references:uuid
14	bin/rails db:migrate
15	bin/rails console # Test: Card.open.count
16	bin/rails test test/models/
17	```
18
19	## Why state records over booleans
20
21	Boolean columns give you:
22	- Current state (open/closed)
23
24	State records give you:
25	- Current state (`closure.present?`)
26	- When it changed (`closure.created_at`)
27	- Who changed it (`closure.user`)
28	- Why it changed (`closure.reason`)
29	- Change history (via events)
30
31	## The pattern
32
33	### Boolean approach (avoid for business state):
34	```ruby
35	# BAD
36	class Card < ApplicationRecord
37	def close
38	update!(closed: true, closed_at: Time.current)
39	end
40
41	scope :open, -> { where(closed: false) }
42	end
43	```
44
45	### State record approach:
46	```ruby
47	# GOOD
48	class Closure < ApplicationRecord
49	# touch: true ensures the parent's updated_at changes when state changes,
50	# which drives cache invalidation (Russian doll caching, ETags, etc.)
51	belongs_to :card, touch: true
52	belongs_to :user, optional: true
53	belongs_to :account, default: -> { card.account }
54
55	validates :card, uniqueness: true
56	end
57
58	class Card < ApplicationRecord
59	has_one :closure, dependent: :destroy
60
61	def close(user: Current.user)
62	create_closure!(user: user)
63	end
64
65	def reopen
66	closure&.destroy!
67	end
68
69	def closed?
70	closure.present?
71	end
72
73	scope :open, -> { where.missing(:closure) }
74	scope :closed, -> { joins(:closure) }
75	end
76	```
77
78	## State record model template
79
80	Every state record model follows this structure:
81
82	```ruby
83	class Closure < ApplicationRecord
84	belongs_to :account, default: -> { card.account }
85	belongs_to :card, touch: true
86	belongs_to :user, optional: true
87
88	validates :card, uniqueness: true
89
90	after_create_commit :notify_watchers
91	after_destroy_commit :notify_watchers
92
93	private
94
95	def notify_watchers
96	card.notify_watchers_later
97	end
98	end
99	```
100
101	## State concern template
102
103	Every state concern follows this structure:
104
105	```ruby
106	module Card::Closeable
107	extend ActiveSupport::Concern
108
109	included do
110	has_one :closure, dependent: :destroy
111
112	scope :open, -> { where.missing(:closure) }
113	scope :closed, -> { joins(:closure) }
114	end
115
116	def close(user: Current.user)
117	create_closure!(user: user)
118	track_event "card_closed", user: user
119	end
120
121	def reopen
122	closure&.destroy!
123	track_event "card_reopened"
124	end
125
126	def closed?
127	closure.present?
128	end
129
130	def open?
131	!closed?
132	end
133
134	def closed_at
135	closure&.created_at
136	end
137
138	def closed_by
139	closure&.user
140	end
141	end
142	```
143
144	## State record with metadata
145
146	When state needs additional data (secure tokens, descriptions):
147
148	```ruby
149	class Board::Publication < ApplicationRecord
150	belongs_to :account, default: -> { board.account }
151	belongs_to :board, touch: true
152
153	has_secure_token :key
154
155	validates :board, uniqueness: true
156
157	def public_url
158	Rails.application.routes.url_helpers.public_board_url(key)
159	end
160	end
161
162	module Board::Publishable
163	extend ActiveSupport::Concern
164
165	included do
166	has_one :publication, dependent: :destroy
167
168	scope :published, -> { joins(:publication) }
169	scope :private, -> { where.missing(:publication) }
170	end
171
172	def publish(description: nil)
173	create_publication!(description: description)
174	track_event "board_published"
175	end
176
177	def unpublish
178	publication&.destroy!
179	track_event "board_unpublished"
180	end
181
182	def published?
183	publication.present?
184	end
185
186	def public_url
187	publication&.public_url
188	end
189	end
190	```
191
192	## Query patterns with state records
193
194	```ruby
195	# Finding by state: positive uses joins, negative uses where.missing
196	Card.open # where.missing(:closure)
197	Card.closed # joins(:closure)
198	Board.published # joins(:publication)
199	Card.golden # joins(:goldness)
200
201	# Complex combinations
202	scope :actionable, -> {
203	where.missing(:closure).where.missing(:not_now).where.missing(:archival)
204	}
205
206	# Sorting by state
207	scope :with_golden_first, -> {
208	left_outer_joins(:goldness)
209	.select("cards.*", "card_goldnesses.created_at as golden_at")
210	.order(Arel.sql("golden_at IS NULL, golden_at DESC"))
211	}

People who liked this also viewed

6 picks

Type

state-records

635stars79forks

View on GitHub

How to install state-records?

thibautbaissac/rails_ai_agents/state-records

$npx -y skills add ThibautBaissac/rails_ai_agents --skill state-records

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# State Records (37signals)
2
3	State as records, not booleans. Instead of `closed: boolean`, create a `Closure` record.
4
5	## Project knowledge
6
7	Tech Stack: Rails 8.2 (edge), UUIDs everywhere, ActiveRecord associations
8	Pattern: One state model per boolean you'd normally add
9	Naming: Noun forms (Closure, Publication, Goldness, NotNow, Archival)
10
11	Commands:
12	```bash
13	bin/rails generate model Closure card:references:uuid user:references:uuid account:references:uuid
14	bin/rails db:migrate
15	bin/rails console # Test: Card.open.count
16	bin/rails test test/models/
17	```
18
19	## Why state records over booleans
20
21	Boolean columns give you:
22	- Current state (open/closed)
23
24	State records give you:
25	- Current state (`closure.present?`)
26	- When it changed (`closure.created_at`)
27	- Who changed it (`closure.user`)
28	- Why it changed (`closure.reason`)
29	- Change history (via events)
30
31	## The pattern
32
33	### Boolean approach (avoid for business state):
34	```ruby
35	# BAD
36	class Card < ApplicationRecord
37	def close
38	update!(closed: true, closed_at: Time.current)
39	end
40
41	scope :open, -> { where(closed: false) }
42	end
43	```
44
45	### State record approach:
46	```ruby
47	# GOOD
48	class Closure < ApplicationRecord
49	# touch: true ensures the parent's updated_at changes when state changes,
50	# which drives cache invalidation (Russian doll caching, ETags, etc.)
51	belongs_to :card, touch: true
52	belongs_to :user, optional: true
53	belongs_to :account, default: -> { card.account }
54
55	validates :card, uniqueness: true
56	end
57
58	class Card < ApplicationRecord
59	has_one :closure, dependent: :destroy
60
61	def close(user: Current.user)
62	create_closure!(user: user)
63	end
64
65	def reopen
66	closure&.destroy!
67	end
68
69	def closed?
70	closure.present?
71	end
72
73	scope :open, -> { where.missing(:closure) }
74	scope :closed, -> { joins(:closure) }
75	end
76	```
77
78	## State record model template
79
80	Every state record model follows this structure:
81
82	```ruby
83	class Closure < ApplicationRecord
84	belongs_to :account, default: -> { card.account }
85	belongs_to :card, touch: true
86	belongs_to :user, optional: true
87
88	validates :card, uniqueness: true
89
90	after_create_commit :notify_watchers
91	after_destroy_commit :notify_watchers
92
93	private
94
95	def notify_watchers
96	card.notify_watchers_later
97	end
98	end
99	```
100
101	## State concern template
102
103	Every state concern follows this structure:
104
105	```ruby
106	module Card::Closeable
107	extend ActiveSupport::Concern
108
109	included do
110	has_one :closure, dependent: :destroy
111
112	scope :open, -> { where.missing(:closure) }
113	scope :closed, -> { joins(:closure) }
114	end
115
116	def close(user: Current.user)
117	create_closure!(user: user)
118	track_event "card_closed", user: user
119	end
120
121	def reopen
122	closure&.destroy!
123	track_event "card_reopened"
124	end
125
126	def closed?
127	closure.present?
128	end
129
130	def open?
131	!closed?
132	end
133
134	def closed_at
135	closure&.created_at
136	end
137
138	def closed_by
139	closure&.user
140	end
141	end
142	```
143
144	## State record with metadata
145
146	When state needs additional data (secure tokens, descriptions):
147
148	```ruby
149	class Board::Publication < ApplicationRecord
150	belongs_to :account, default: -> { board.account }
151	belongs_to :board, touch: true
152
153	has_secure_token :key
154
155	validates :board, uniqueness: true
156
157	def public_url
158	Rails.application.routes.url_helpers.public_board_url(key)
159	end
160	end
161
162	module Board::Publishable
163	extend ActiveSupport::Concern
164
165	included do
166	has_one :publication, dependent: :destroy
167
168	scope :published, -> { joins(:publication) }
169	scope :private, -> { where.missing(:publication) }
170	end
171
172	def publish(description: nil)
173	create_publication!(description: description)
174	track_event "board_published"
175	end
176
177	def unpublish
178	publication&.destroy!
179	track_event "board_unpublished"
180	end
181
182	def published?
183	publication.present?
184	end
185
186	def public_url
187	publication&.public_url
188	end
189	end
190	```
191
192	## Query patterns with state records
193
194	```ruby
195	# Finding by state: positive uses joins, negative uses where.missing
196	Card.open # where.missing(:closure)
197	Card.closed # joins(:closure)
198	Board.published # joins(:publication)
199	Card.golden # joins(:goldness)
200
201	# Complex combinations
202	scope :actionable, -> {
203	where.missing(:closure).where.missing(:not_now).where.missing(:archival)
204	}
205
206	# Sorting by state
207	scope :with_golden_first, -> {
208	left_outer_joins(:goldness)
209	.select("cards.*", "card_goldnesses.created_at as golden_at")
210	.order(Arel.sql("golden_at IS NULL, golden_at DESC"))
211	}

People who liked this also viewed

6 picks

Type