Copyright 2003, 2014 Nikolas S. Boyd. Permission is granted to copy this document provided this copyright statement is retained in all copies.

Trace Cards

Nik Boyd


This paper introduces a new technique for capturing requirements information on index cards, including policy cards, intelligence quality cards and quantity cards, and face cards. The origins, purpose and usage of each card type are discussed, and a few representative examples are provided. Some considerations regarding how trace cards may be used in conjunction with CRC cards are also offered.


Software developers need simple ways to capture and share knowledge. Large (4" x 6") index cards provide a convenient form factor for capturing and sharing knowledge. Index cards are convenient from several standpoints:

For these reasons, index cards can facilitate some of the most difficult aspects of software development, including not only solution design, but also problem definition. Just so, trace cards are primarily problem oriented. Trace cards offer a convenient and efficient way to capture and share knowledge about business policies, business intelligence needs, and business activities. They offer a way to keep object-oriented software designs aligned with business policies and priorities.

Precedent and Context

During the late 1980s, Ward Cunningham and Kent Beck introduced the use of CRC cards1 (Class, Responsibility, Collaborator) as a technique for capturing and sharing object-oriented design decisions. Since then, the technique has become popular among object-oriented software developers, largely due to its simplicity and effectiveness. Just as developers need a convenient way to capture and share design decisions, requirements analysts need simple ways to capture and share knowledge about business policies, business intelligence, and business activities during software development.

Language dominates software development, especially during the earliest phases of a project when the vast majority of time is spent discussing business objectives and the intended effects for a project. Ultimately, all software elements, components and composites are named, and they are often organized based on linguistic affinities, e.g., as objects and sentential expressions in object-oriented designs. So, the words used in discussions about business problems and solutions will naturally have a dramatic and durable impact on the resulting software. Beck and Cunningham emphasized this point with respect to CRC cards:

"The class name of an object creates a vocabulary for discussing a design. Indeed, many people have remarked that object design has more in common with language design than with procedural program design. We urge learners (and spend considerable time ourselves while designing) to find just the right set of words to describe our objects, a set that is internally consistent and evocative in the context of the larger design environment."

"Responsibilities identify problems to be solved. The solutions will exist in many versions and refinements. A responsibility serves as a handle for discussing potential solutions. The responsibilities of an object are expressed by a handful of short verb phrases, each containing an active verb. The more that can be expressed by these phrases, the more powerful and concise the design. Again, searching for just the right words is a valuable use of time while designing."

Perhaps even more so, discovering just the right words is valuable when capturing discussions about business policies, business intelligence, and business activities. This knowledge is the requisite fodder consumed during requirements analysis and solution design, and it establishes the context within which software solutions will be developed and evolved.

In 2003, Eric Evans introduced Domain-Driven Design,10 with a set of software design practice patterns that explicitly incorporates business and problem terminology into software designs. A key practice in DDD is the development of an ubiquitous language, shared by all members of a software development team, including developers, domain experts, solution users, owners and sponsors.

Diagrams vs. Narratives

How should knowledge about business problems be captured? What kind of residue should remain and be maintained after solution development? These questions often arise during software development projects. Most modern human interfaces are graphical, and so require graphical designs. Also, since the early 1980s, graphical notations have become a popular way to visualize other aspects of software.

Some methodologists have offered elaborate graphical notations for capturing knowledge about business elements and activities, e.g., the Unified Modeling Language2 (UML). Such diagrams provide useful overviews and help us visualize the structural relationships between software elements, components, and composites. However, as design artifacts and residues, diagrams are expensive to create and maintain and usually require special tools. Also, they are prone to complexity and (intentionally) limited in their expressiveness.

Because of their rich structure and interconnections, most goals and usage scenarios are best expressed as structured narratives. Narratives are easy to create and maintain and usually require only simple tools, such as a text editor or hypertext (HTML) editor. Also, narratives are easier to simplify and provide the full expressiveness of natural language. Given that modern software extensively leverages language metaphors, structured narratives offer a better fit for maintaining the traceability and the expressive proximity of the resultant software to its originating requirements.

Additionally, there are systematic ways to analyze, transform, and simplify natural language statements into a form that lends itself better to software solution design. The details of such analysis are beyond the scope of this present paper. However, those interested in can find these details described in the EDUCE pattern language. 11 There are several aspects of this work that are inspired in part by EDUCE.

Planning and Tracking Success

Success is rarely accidental. It must usually be planned. This is especially true for software development. Software is a conceptual artifact. Software developers need conceptual leverage, techniques that make tackling the inherent complexity of software solution design tractable. First and foremost, software developers need to ensure that their work products align with the policies and improve the activities of a business.

Software solutions support and improve business activities. Business activities are directed by business policies. Business intelligence provides the management community with data critical to the guidance of business activities and the maintenance of their alignment with business policies.

Trace cards extend conceptual thinking beyond objects into their business origins. They provide ways to capture and share knowledge about business policies (vision and mission), business intelligence (qualities and quantities), and business activities (workflows and solution usage). They also help establish and maintain alignment and traceability across requirements levels.

Solution designs are usually impacted by various forces and constraints outside of the control of a solution designer. Engineers evaluate and attempt to balance the known forces based on their known or discovered effects. To properly evaluate and balance a set of forces, an engineer needs to know not only what these forces are, but also how they relate to each other. Software designers need to know not only what to accomplish and how, but also why. Trace cards provide answers to some of these questions.

Goal Levels

Explicitly identifying the nature and level of goals can help us to align technology development with business objectives. In Writing Effective Use Cases,3 Alistair Cockburn identifies several goal levels used for requirements. However, there are certain kinds of business policies that were not included. The following proposed goal levels extend those he offered and continues the metaphor of verticality he used. These levels can also be found in my proposed conceptual model for software requirements.4

Table 1. Goal Levels

Level     Nature     Source Icon
Vision   Policy   Governor
Mission   Critical Policy   Governor
Mission   Central Policy   Governor
Mission   Peripheral Policy   Governor
Organization   External   Customer,
Partner, Supplier
Organization   Internal   Requestor
System   External   Expector
System   Internal   Interface
Component   External   Component

Policy Cards

Business policies establish the ends, means, and central values of a business. These policies traditionally appear in business vision, mission, and value statements. These core business documents originate in the corporate governance community, especially the board of directors, the corporate officers, and the management team.

Policy cards generally derive their focus from business governance policy statements: vision, mission, values. Policy cards provide a way to capture and organize selected business policies on index cards. They can be used:

A policy card should always capture the following information:

A policy card may also exhibit one of two organizational variations: organized by theme and organized by subject. Card templates (1 and 2) for these two variations can be found in Appendix A.

When policy concerns are organized by theme (see Card Template 1),

When policy concerns are organized by subject (see Card Template 2),

Policy cards can be used to capture ends statements, especially from vision and mission statements. However, ends statements differ from means statements in a subtle but significant way. Ends statements focus on effects rather than efforts. For some further remarks about ends statements and their formulation, see Quality Alignment and Quality Inventories.5

Policy Card Examples

Here follows discussions and example policy cards with reference to a specific worked out example problem: ECO Storage Depot. Here's a sample of how an overall corporate vision statement might be captured for the ECO Storage Depot.

Card 1. ECO Depot Vision
reputation engagement count
world-class hazmat storage excels in hazmat storage safety innovation, and sets the
  highest standards for safe hazmat storage safety
  throughout the world, resulting in
growth in storage facilities and services for client organizations worldwide

The depot is subject to external regulatory oversight by the EPA. If the depot becomes unsafe, the EPA will close it. Therefore, the continuity of depot business operations requires depot safety. To further enhance depot safety, the depot governors has established additional policies regarding depot operations.

Card 2. Safety as a Mission Theme
safety regulatory compliance
safe hazmat storage ensure safety compliance
  minimize depot vulnerability
  prevent depot closure
  prevent litigation 
  accept all drums that can be safely stored 
  allocate drum storage space within licensed limits  
  allocate drum storage space to minimize vulnerability 

These critical mission objectives can be divided into those that are externally oriented (and visible), and those that are internally oriented toward depot operations.

Card 3. Drum Storage Allocation Qualities (External)
storage safety storage allocation
safe storage allocation ensures regulatory compliance
  prevents depot closure
  prevents local litigation

Card 4. Drum Storage Allocation Qualities (Internal)
storage safety storage allocation
safe storage allocation accept all drums that can be safely stored 
  allocate drum storage space within licensed limits  
  allocate drum storage space to minimize vulnerability 
  minimize depot vulnerability 

Intelligence Cards

Business intelligence offers management the information needed to guide the business in the directions established by business policies. Business intelligence regards the various business quality concerns, especially the (quantitative) measurement of the relevant business products and activities.

Intelligence cards are generally paired: a quality card with a quantity card. A quality card collects knowledge about a single business quality concern, while the corresponding quantity card collects details about the measurements related to that quality concern. Together, they can be used:

Templates (3 and 4) for these two cards can be found in Appendix A. To link the quality and quantity cards, they both share the following information:

A quality card (see Card Template 3) captures the following additional information:

A quantity card (see Card Template 4) captures the following additional information:

Intelligence Card Examples

Safety of the ECO Depot has specific measurable physical criteria, constraints on the storage of hazardous chemicals that must be met to remain in compliance with EPA regulations and the additional constraints imposed by the depot governors. What are those quality constraints?

Card 5. Drum Storage Questions
safety, vulnerability proximity, drum counts
what makes the depot safe? no building contains disallowed drum combos
what makes the depot vulnerable? when any pair of neighboring buildings is full
how close are neighboring buildings?  when their walls are 5 meters apart or less  
what makes a storage building full when each hazard type limit has been reached 
each storage building:  has a storage license for each hazard type
each building hazard type license limits the number of drums stored  
thus, each storage building:  must have a drum storage inventory

These quality constraints may then be quantified and made measurable.

Card 6. Drum Storage Conditions and Measures
vulnerability proximity, drum counts
vulnerable depot = vulnerable storage building pair
vulnerable buildings = neighboring pair of full storage buildings
neighboring buildings = building walls within 5 meters proximity
full storage building = (hazard type storage capacity = 0) per hazard type
hazard type storage capacity = (drum storage limit - drum count) per hazard type
building drum storage limit from: building drum storage license (per hazard type)
building drum count from: building drum inventory

As well, the EPA defines the following safety criteria.

Card 7. Drum Storage Regulations
safety regulatory compliance
unsafe storage building = a building stores hazard type 1 and hazard type 2
safe storage building = a building stores hazard type 3 and hazard type 1
  = a building stores hazard type 3 and hazard type 2

Face Cards

Face cards derive their name from their dominant focus on interfaces and interactions, the contracts and conversations that take place between interaction participants. Face cards provide a way to capture business activities and their stakeholders as use cases on index cards. A template for face cards can be found in Appendix A (see Card Template 5).

Face cards can be used as a starting point for writing use cases, or subsequently for use case analysis, especially in conjunction with agile software development methods. Detailed discussions of use cases and their components can be found in Writing Effective Use Cases3 by Alistair Cockburn. Face cards intentionally simplify use cases by eliminating some of the details that can be found in a "fully dressed" use case.

A face card captures at least the following information:

A face card may also capture preconditions and postconditions:

There are a few features that distinguish face cards as a medium for capturing use cases. As a form of structured narrative, face cards emphasize the identification of stakeholders and their interests, their expectations, their contractual obligations, and their collaborative responsibilities.

The format of a face card reinforces this by separating the stakeholders (in the left column) from their interests, expectations, obligations, and responsibilities (in the right column). As a result, these descriptions have a distinctive narrative style. Most conditions are expressed using an active verb phrase with present tense. Two exceptions include preconditions and some triggers. Preconditions use an active verb with past tense. Some triggers may also use past tense.

When applied to a business interface, the conditions and actions often describe the business partners and their interests, their expectations, their contractual obligations, and their collaborative responsibilities. But, they may also describe value exchanges, goods exchanges, and information exchanges.

When applied at a human interface, the conditions and actions often describe the business stakeholders and their interests, their expectations, their functional obligations, and their collaborative responsibilities. But, they may also describe information exchanged between a human operator and the system under development.

When applied at a component interface, the conditions and actions often describe the clients and collaborators, and their expectations, their functional obligations, and collaborative responsibilities.

When used at these later, more detailed requirements levels, face cards can serve as an intermediate residue between use cases and designs. They can help identify candidate objects and responsibilities at human interfaces and component interfaces. This information can then be fed forward into the CRC cards used for responsibility-driven and domain-driven object-oriented design.

Here follows some representative samples of face cards for the ECO Depot. These samples are taken from a more complete set available here. These face cards show the stakeholders with their interests, the postconditions, and the main success scenarios, including the scenario initiation triggers.

Face Card Examples

An ECO depot manager must monitor the depot and ensure its safety. The system must help each depot manager fulfill this responsibility by reportng the depot status in detail.

Card 8. Depot Monitoring
depot manager monitors depot
depot manager wants depot status
depot governors want to ensure depot safety compliance
depot remains safe
depot buildings remain safe
depot manager requests depot status report
system reports depot status, including:
      a vulnerable building count
      a vulnerability indicator for each building
      a drum count per hazard for each building

To ensure depot safety, the system needs to know which hazard types each storage building has been licensed to store. To minimize depot vulnerability, the system needs to know which buildings are neighbors. Thus, the system needs a map of the depot and a storage license inventory. A depot manager is responsible for supplying this information.

Card 9. Depot Map Maintenance
depot manager maintains depot map
depot manager wants accurate depot map
depot governors want to ensure depot safety compliance
depot map reflects depot building characteristics and layout
depot manager requests depot map maintenance
system presents depot map maintenance operations
depot manager selects a depot map maintenance operation

To ensure depot safety, a depot manager must supply the system with accurate information about the depot buildings, including their locations and physical dimensions.

Card 10. Depot Building Additions
depot manager adds depot building
depot manager wants accurate depot map
depot governors want to ensure depot safety compliance
depot map reflects depot building characteristics and layout
depot manager selects add depot building
system accepts building description, including:
      physical building dimensions
      physical location in depot
      type: staff building or storage building
      occupant capacity for a staff building
      drum licenses for a storage building
      actual drum count for a storage building

Further Considerations

From a certain perspective, the prevailing state of software development practice has inverted priorities. Typically, we rush (or are rushed) to implement solutions before we sufficiently understanding the problems we're being asked to solve. Stakeholders tacitly assume that software solutions will improve the quality of their lives and business activities. But, such benefits still elude our collective grasp far too often. Without giving quality due consideration, without spending significant time discussing quality expectations explicitly and systematically, the achievement of a sufficient solution that satisfies its requirements (satisficing) will continue to be accidental and haphazard rather than intentional and sure. The "rubber meets the road" where requirements meet designs.

Historically, the practice of responsibility-driven design with CRC cards has focused primarily on knowledge (noun phrases) and behavior (verb phrases) to the virtual exclusion of qualities (as expressed by descriptive adjectives). The absence of quality responsibilities can usually be traced back to the absence of quality considerations in the original requirements. Quality requirements often receive little or no consideration during requirements gathering, especially in comparison with the emphasis often placed on form and function.

But, the consideration of object responsibilities should properly include qualities in addition to knowledge and behavior. Conceptually, we can understand qualities as expressive of the dimension (and states) of being. So, objects have and ensure qualities in addition to having knowledge and doing behaviors. Objects should know why in addition to what and how. Every object

knows     some information (with structure)     know what
does     some behaviors (with functions)     know how
ensures     some qualities (with conditions)     know why
is     some concept (with a role and relations)      

In practice, object-oriented designs entail strong contracts between servers and their clients. So, a server object imposes responsibilities (especially for quality) on its clients as preconditions to the proper usage of its services. Likewise, a server object offers quality guarantees to its clients (as postconditions and invariants). Method preconditions (ensured by clients), method postconditions (ensured by servers), invariants (ensured by servers), constraints, and qualified class names all offer the potential for consideration with respect to quality requirements.

For example, reconsider Card 6 above. This example demonstrates how policy constraints can be analyzed for their conditions, and how apparently simple constraints can entail quite elaborate quality and measurement requirements when explored in detail. Notice that the definitions of named quality conditions often relate values and may entail further decompositions of their measurements, like the following:

full storage building =
( hazard type storage capacity = 0 ) per hazard type

Notice that this constraint requires measurements in multiple dimensions, including a licensed limit (per building, per hazard type), and an actual stored drum count (per building, per hazard type). Consequently, inventories must be maintained per building for both licenses and stored drums.

During requirements analysis (and during design), it's often useful to explore how quality themes and conditions decompose into value relations and the measurements and metrics needed to test them. Explicitly identifying and naming test conditions also improves the testability of object-oriented designs. Intelligence cards can be used to capture and share the results of such analysis. Thus, identifying and naming quality conditions and their component value relations can play an important part in ensuring software solution quality.

Perhaps this extended understanding of responsibilities can help improve our object-oriented designs, especially in the context of CRC cards. Both client and server responsibilities can be listed on a CRC card. Enumerating only the responsibilities for knowledge and behavior weakens a class design, while also enumerating the respective responsibilities of both a server and its clients strengthens a design into a contract, especially when quality responsibilities are included. This simple practice also increases the testability of the design if the quality conditions are ultimately exposed as test methods in the implementation. So, this practice can serve as a natural adjunct for test-driven development approaches like extreme programming (XP),9 and can also serve as a natural adjunct to language focused approaches like domain-driven design (DDD).10

Table 2. Card and Traceability Summary

Card Type     Knowledge   Sources   Traceability Intent

Policy Card   quality concerns, benefits (value)   governors: board + officers, vision, mission, values   tied to business policy statements: vision, mission, values
Intelligence Cards   concerns, goals, metrics, measurement linkage   requestors: activity managers, other stakeholders, objectives, goals   ties business intelligence requirements back to business policies and priorities
Face Card   goals, interests, expectations,
obligations, interactions
  expectors: activity participants, users and other stakeholders, business contracts, user stories   ties business activities and activity improvement goals back to business policies and priorities
CRC Card   responsibilities for: quality, behavior, knowledge   developers: design sessions and decisions   ties solution designs back to business activities and business intelligence requirements


  1. Kent Beck, Ward Cunningham. A Laboratory for Teaching Object-Oriented Thinking. OOPSLA 1989 Conference Proceedings. ACM SIGPLAN Notices 24(10), 1989.

  2. Object Management Group. UML™ Resource Page.

  3. Alistair Cockburn. Writing Effective Use Cases. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-702258.

  4. Nik Boyd. A Conceptual Model for Software Requirements.

  5. Nik Boyd. Quality Alignment and Quality Inventories.

  6. Victor Basili, Gianluigi Caldiera, Dieter Rombach. The Goal Question Metric Paradigm. Encyclopedia of Software Engineering. John Wiley & Sons, Inc., 2001. ISBN 0-471-37737-6.

  7. Scott Whitmire. Object-Oriented Design Measurement. John Wiley & Sons, Inc., 1997. ISBN 0-471-13417-1.

  8. Ron Jeffries, Ann Anderson, Chet Hendrickson, Kent Beck. Extreme Programming Installed. Addison-Wesley Publishing, Inc., 2001. ISBN 0-201-70842-6.

  9. Kent Beck, Extreme Programming Explained: Embrace Change. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-61641-6.

  10. Eric Evans. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley Publishing, Inc., 2003. ISBN 0-321-12521-5.

  11. Nik Boyd. EDUCE: A Pattern Language of Language Patterns.

Appendix A. Trace Card Templates

Template 1. Theme-Oriented Policy Card
quality / value theme basic measure
quality instantiation benefit description

Template 2. Subject-Oriented Policy Card
concern subject type specific concern subject
quality instantiation benefit description

Template 3. Intelligence Quality Card
quality concern essential metric
quality concern subject stakeholder role
stakeholder objective goal / target
questions metrics

Template 4. Intelligence Quantity Card
quality concern essential metric
concern subject stakeholder role
conditions / measurements sources / instruments

Template 5. Face Card
primary actor / role primary goal
stakeholder interest(s)
minimal guarantee recipient minimal guarantee
success guarantee recipient success guarantee
precondition guarantor precondition
trigger actor scenario trigger
step actor scenario step (activity)